Quickstart

A 10-minute walk-through: from zero to your first authenticated API call.

What you'll build

By the end of this page you'll have fetched a single employee record using a server-to-server OAuth token. Budget: about 10 minutes if you already have a Rise account.

Prerequisites

• A Rise account. If you don't have one, ask your Rise account manager or email developers@risepeople.com.
• curl (or any HTTP client)
• 5 minutes

Step 1 — Register an OAuth app

1. Sign in at https://risepeople.com
2. Go to Settings → Developer → OAuth applications
3. Click Create application
4. Fill in:
   • Name: Quickstart demo
   • Client type: Confidential (we're calling server-to-server)
   • Scopes: check employees:read only
5. Save and copy the client_id + client_secret. The secret is shown only once.

Step 2 — Get an access token

curl

export RISE_CLIENT_ID="..."
export RISE_CLIENT_SECRET="..."

curl -s -X POST https://api.risepeople.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$RISE_CLIENT_ID" \
  -d "client_secret=$RISE_CLIENT_SECRET" \
  -d "scope=employees:read" \
  | jq -r .access_token \
  > .rise_token

Node.js

import fs from "node:fs";

const res = await fetch("https://api.risepeople.com/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.RISE_CLIENT_ID,
    client_secret: process.env.RISE_CLIENT_SECRET,
    scope: "employees:read",
  }),
});

if (!res.ok) throw new Error(`Token request failed: ${res.status}`);

const { access_token } = await res.json();
fs.writeFileSync(".rise_token", access_token);
console.log("Saved access token to .rise_token");

If this fails with invalid_client, double-check your client ID and secret. If it fails with invalid_scope, the OAuth app isn't configured with employees:read — go back to Step 1.

Step 3 — Make your first call

List the first 10 employees in your account, page 1:

curl

TOKEN=$(cat .rise_token)

curl -s 'https://api.risepeople.com/v1/employees?page[number]=1&page[size]=10' \
  -H "Authorization: Bearer $TOKEN" \
  | jq

Node.js

import fs from "node:fs";

const token = fs.readFileSync(".rise_token", "utf8");

const url = new URL("https://api.risepeople.com/v1/employees");
url.searchParams.set("page[number]", "1");
url.searchParams.set("page[size]", "10");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${token}` },
});

if (!res.ok) {
  const body = await res.json();
  const first = body.errors?.[0];
  throw new Error(`API error: ${first?.code}${first?.detail ? " — " + first.detail : ""}`);
}

const { data, meta, links } = await res.json();
console.log(`Got ${data.length} of ${meta.record_count} employees`);
console.log(data[0]);
if (links?.next) console.log(`Next page: ${links.next}`);

Expected response (truncated):

{
  "data": [
    {
      "id": "1001",
      "type": "employees",
      "attributes": {
        "employee_number": "1001",
        "first_name": "Avery",
        "last_name": "Tran",
        "email": "avery@acme.example",
        "status": "active",
        "department": "Engineering"
      }
    }
  ],
  "meta": {
    "record_count": 42
  },
  "links": {
    "first": "https://api.risepeople.com/v1/employees?page[number]=1&page[size]=10",
    "next":  "https://api.risepeople.com/v1/employees?page[number]=2&page[size]=10",
    "last":  "https://api.risepeople.com/v1/employees?page[number]=5&page[size]=10"
  }
}

That's a JSONAPI-style paginated list. Increment page[number] (or follow links.next) for the next page. The meta key carrying the total is named record_count for some services and count for others — check the per-endpoint API Reference.

Step 4 — Fix your first error

Try calling an endpoint you don't have the scope for:

curl -s https://api.risepeople.com/v1/payroll/runs \
  -H "Authorization: Bearer $TOKEN" \
  | jq

You should see:

{
  "type":   "https://developer.risepeople.com/errors/insufficient-scope",
  "title":  "Insufficient Scope",
  "status": 403,
  "detail": "Token is missing required scope `payroll:read`.",
  "instance": "/v1/payroll/runs"
}

(Insufficient-scope rejections use the application/problem+json format — see Errors → Problem details.)

Go back to your OAuth app, add payroll:read, request a fresh token (Step 2), and the call will succeed. This is the normal debugging loop — scope mismatches are 403, not 401.

What's next

• Authentication — Authorization Code + PKCE for apps that act on behalf of a user
• API Reference → Auth — every OAuth endpoint documented with a live "Try It" button
• API Reference → Reporting — payroll and employee reports
• Rate limits before you start batch jobs
• Errors for the full problem-details envelope

If you hit a wall, quote the request_id from the response when you file a support ticket at support.risepeople.com — it lets us trace your exact call.