API docs

Appearance

On this page

Lists beta ​

Endpoints ​

GET /v1/directory/lists
GET /v1/directory/lists/:id
GET /v1/directory/lists/:list_id/people

INFO

These endpoints are read-only and return People and Lists as they appear in the Directory. If your intent is to use the API as a sync source, use the Syncing endpoints to create, update, and delete synced contacts and lists.

List lists ​

GET /v1/directory/lists

Returns a page of lists in reverse chronological order (newest created_at first).

Parameters ​

NameOptionalDefaultDescriptionOptions
Pagination parametersSee pagination for more information.
sortoptionalcreated_atSort field.created_at
orderoptionaldescSort order.asc, desc
limitoptional50Number of lists per page. Must be between 1 and 100.

Returns ​

A page of list objects. See Retrieve a list for more information on the list object.

Example responses

Success response (200)

json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/directory/lists?cursor=eyJzb3J0IjoiY3JlYXRlZF9hdCIsIm9yZGVyIjoiZGVzYyJ9",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "list",
      "id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
      "title": "All Employees",
      "description": "All active employees across the company",
      "email_address": "all-employees@example.com",
      "source_type": "synced",
      "category": "standard",
      "memberships_count": 100,
      "subdirectory_id": null,
      "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
      "creator": "olly@example.com",
      "created_at": "2025-08-12T14:30:00.000Z",
      "urls": {
        "people": "/v1/directory/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/people"
      }
    },
    {...},
    {...},
    {...},
    {...}
  ]
}

Error response (422)

json
{
  "error": {
    "sort": ["must be one of: created_at"],
    "order": ["must be one of: asc, desc"],
    "limit": ["must be greater than 0"]
  }
}

Errors ​

CodeDescription
422Invalid request, supplied parameters did not pass validation.

Retrieve a list ​

GET /v1/directory/lists/:id

Gets the details of a single list.

Parameters ​

NameOptionalTypeDescription
idrequiredstringThe ID of the list to retrieve.

Returns ​

A list object.

NameTypeDescription
source_typestringHow the list is populated. One of static, synced, automatic, or csv_import.
categorystringOne of standard, location, department, or team.
memberships_countnumberThe number of people on the list.
subdirectory_idstringThe ID of the subdirectory the list belongs to, or null.
creator_idstringThe ID of the user who created the list, or null.
creatorstringThe email address of the user who created the list, or null.
Example responses

Success response (200)

json
{
  "object": "list",
  "id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
  "title": "All Employees",
  "description": "All active employees across the company",
  "email_address": "all-employees@example.com",
  "source_type": "synced",
  "category": "standard",
  "memberships_count": 100,
  "subdirectory_id": null,
  "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
  "creator": "olly@example.com",
  "created_at": "2025-08-12T14:30:00.000Z",
  "urls": {
    "people": "/v1/directory/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/people"
  }
}

Error response (404)

json
{
  "error": "List not found"
}

Errors ​

CodeDescription
404List with the given ID was not found.

List people ​

List people on a list ​

GET /v1/directory/lists/:list_id/people

Returns a page of people who are members of the list.

Parameters ​

NameOptionalDefaultDescriptionOptions
list_idrequiredThe ID of the list whose people to retrieve.
Pagination parametersSee pagination for more information.
sortoptionalidSort field.id
orderoptionaldescSort order.asc, desc
limitoptional50Number of people per page. Must be between 1 and 100.

Returns ​

A page of person summary objects. See Retrieve a person for more information on the person object.

Example responses

Success response (200)

json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/directory/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/people?cursor=eyJzb3J0IjoiaWQiLCJvcmRlciI6ImRlc2MifQ",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "person",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+12345678910",
      "time_zone": "America/Chicago",
      "created_at": "2025-08-12T14:30:00.000Z",
      "urls": {
        "details": "/v1/directory/people/937ccbe2-4cb5-4c76-96bf-29510b514dfa"
      }
    },
    {...},
    {...},
    {...},
    {...}
  ]
}

Error response (404)

json
{
  "error": "List not found"
}

Error response (422)

json
{
  "error": {
    "sort": ["must be one of: id"],
    "order": ["must be one of: asc, desc"],
    "limit": ["must be greater than 0"]
  }
}

Errors ​

CodeDescription
404List with the given ID was not found.
422Invalid request, supplied parameters did not pass validation.