API docsAppearance
People beta
Endpoints
GET /v1/directory/people
GET /v1/directory/people/:idINFO
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 people
GET /v1/directory/peopleReturns a page of people.
Parameters
| Name | Optional | Default | Description | Options |
|---|---|---|---|---|
| Pagination parameters | See pagination for more information. | |||
| sort | optional | id | Sort field. | id |
| order | optional | desc | Sort order. | asc, desc |
| limit | optional | 50 | Number of people per page. Must be between 1 and 100. |
Returns
A page of person summary objects.
Example responses
Success response (200)
json
{
"object": "array",
"has_more": true,
"next": "/v1/directory/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 (422)
json
{
"error": {
"sort": ["must be one of: id"],
"order": ["must be one of: asc, desc"],
"limit": ["must be greater than 0"]
}
}Errors
| Code | Description |
|---|---|
| 422 | Invalid request, supplied parameters did not pass validation. |
Retrieve a person
GET /v1/directory/people/:idGets the details of a single person.
Parameters
| Name | Optional | Type | Description |
|---|---|---|---|
| id | required | string | The ID of the person to retrieve. |
Returns
A person object. The attributes array contains one entry per directory attribute set on the person, with the attribute's id, name, and value. Date values are ISO 8601 strings.
Example responses
Success response (200)
json
{
"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",
"attributes": [
{
"id": "5f0c1a2e-8d3b-4c7a-9e21-6b4d8f0a1c3e",
"name": "Department",
"value": "Sales"
},
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Start date",
"value": "2024-03-01"
}
]
}Error response (404)
json
{
"error": "Person not found"
}Errors
| Code | Description |
|---|---|
| 404 | Person with the given ID was not found. |