Positions

Positions are the job titles configured for staff in your organisation (for example "Support Worker" or "Team Leader"). This is a reference lookup returned as a cursor-paginated list of position objects. Listing positions requires the read:users scope.

The position model

The position model is a lightweight reference object. A position has no numeric id — it is identified by its name, which is also the cursor used for pagination.

Properties

Name
object
Type
string
Description
The object type. Always position.
Name
name
Type
string
Description
The position title. This is the position's unique identifier and the value you pass to starting_after when paging.
Name
livemode
Type
boolean
Description
true when the object was returned by a live-mode key (ds_live_…), false in test mode.

GET/v1/positions

List positions

Returns a paginated list of the active position titles in your organisation, ordered alphabetically by name. The response is the standard list envelope (object: "list"). Requires the read:users scope.

Optional attributes

Name
limit
Type
integer
Description
The number of objects to return, 1–100. Defaults to 25.
Name
starting_after
Type
string
Description
A cursor for pagination. Pass the name of the last position from the previous page to fetch the next page.

Iterate while has_more is true, passing the name of the last item in data as starting_after on the next request. Positions have no numeric id, so the name string is the cursor.

Request

GET

/v1/positions

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

Response

{
  "object": "list",
  "url": "/v1/positions",
  "has_more": true,
  "data": [
    {
      "object": "position",
      "name": "House Manager",
      "livemode": true
    },
    {
      "object": "position",
      "name": "Support Worker",
      "livemode": true
    },
    {
      "object": "position",
      "name": "Team Leader",
      "livemode": true
    }
  ]
}