Quickstart

This guide gets you from zero to your first Diversity Sync API request. You'll create a scoped API key, exchange it for an access token, and list your organisation's staff.

Before you start, create an API key in your Diversity Sync workspace under Admin → API Keys (you'll need the write:api_keys permission). Give it the read:users scope for this example, and copy it when it's shown — it isn't shown again.

Step 1: Get an access token

Exchange your API key for a short-lived access token. Tokens last 15 minutes, so fetch a new one whenever the previous one expires.

POST

/oauth/token

curl https://api.diversitysync.com/oauth/token \
  -H "Authorization: Bearer {api_key}"

Step 2: Make your first request

Use the access token as a bearer token to list active staff. Results are paginated — see Pagination.

GET

/v1/staff

curl -G https://api.diversitysync.com/v1/staff \
  -H "Authorization: Bearer {access_token}" \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/staff",
  "has_more": false,
  "data": [
    {
      "object": "staff",
      "id": 482,
      "ref": "f4b9c0a1e2d3…",
      "name": "Jordan Avery",
      "email": "jordan.avery@example.org",
      "position": "Support Worker",
      "employmentType": "Full-time",
      "livemode": true
    }
  ]
}

Read the docs for the Staff endpoint

What's next?

Great — you've made your first request. Here's where to go next:

Authentication — the full key → token flow and scopes
Staff and Participants — the available resources
Pagination — working with paginated lists
Errors — status codes and error shapes