Contacts
List contacts
Read contacts in your workspace, newest first.
GET
/api/v1/contactsOn this page
Authentication
Send a RouteKite API key as a Bearer token. This endpoint requires the audience:read or audience:write scope.
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Required | Bearer rk_ API key. The key determines the workspace. |
Response
| Name | Type | Requirement | Description |
|---|---|---|---|
object | string | Always | Always list. |
data | contact[] | Always | Contacts on the current page, with ID, email, names, state, consent, and timestamps. |
has_more | boolean | Always | True when more contacts match the current filters. |
next_cursor | string or null | Always | Pass as cursor for the next page. Null marks the end. |
Query parameters
| Name | Type | Description |
|---|---|---|
| limit | integer | 1 to 100. Defaults to 50. |
| cursor | string | The next_cursor from the previous page. |
| state | string | subscribed, unsubscribed, or archived. |
| list_id | UUID | Restrict results to members of this workspace list. |
| search | string | Match email addresses, up to 200 characters. |
Pagination
Pass next_cursor unchanged as cursor with the same filters to fetch the next page. Stop when next_cursor is null.
Errors
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | One or more request fields are invalid. | Correct the request and retry. |
| 401 | UNAUTHORIZED | The API key is missing or invalid. | Send a valid Bearer API key. |
| 403 | FORBIDDEN | The key does not have the required scope. | Use a key with the scope shown above. |
| 429 | RATE_LIMITED | The API key or workspace has reached its request limit. | Wait for the Retry-After interval before retrying. |
| 503 | RATE_LIMIT_UNAVAILABLE | RouteKite could not check request limits. | Retry shortly. |
| 500 | INTERNAL_ERROR | RouteKite could not complete the contact operation. | Retry shortly. Reuse the same Idempotency-Key for write retries. |
| 400 | INVALID_CURSOR | The pagination cursor is invalid. | Use next_cursor unchanged or restart the list without a cursor. |
| 503 | CONTACTS_UNAVAILABLE | Contacts or list membership could not be loaded. | Retry shortly. |