Skip to documentation
Dashboard
Contacts

List contacts

Read contacts in your workspace, newest first.

GET/api/v1/contacts
On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the audience:read or audience:write scope.

Required headers
NameTypeRequirementDescription
AuthorizationstringRequiredBearer rk_ API key. The key determines the workspace.

Response

Response fields
NameTypeRequirementDescription
objectstringAlwaysAlways list.
datacontact[]AlwaysContacts on the current page, with ID, email, names, state, consent, and timestamps.
has_morebooleanAlwaysTrue when more contacts match the current filters.
next_cursorstring or nullAlwaysPass as cursor for the next page. Null marks the end.

Query parameters

NameTypeDescription
limitinteger1 to 100. Defaults to 50.
cursorstringThe next_cursor from the previous page.
statestringsubscribed, unsubscribed, or archived.
list_idUUIDRestrict results to members of this workspace list.
searchstringMatch 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

StatusCodeWhat it meansWhat to do
400INVALID_REQUESTOne or more request fields are invalid.Correct the request and retry.
401UNAUTHORIZEDThe API key is missing or invalid.Send a valid Bearer API key.
403FORBIDDENThe key does not have the required scope.Use a key with the scope shown above.
429RATE_LIMITEDThe API key or workspace has reached its request limit.Wait for the Retry-After interval before retrying.
503RATE_LIMIT_UNAVAILABLERouteKite could not check request limits.Retry shortly.
500INTERNAL_ERRORRouteKite could not complete the contact operation.Retry shortly. Reuse the same Idempotency-Key for write retries.
400INVALID_CURSORThe pagination cursor is invalid.Use next_cursor unchanged or restart the list without a cursor.
503CONTACTS_UNAVAILABLEContacts or list membership could not be loaded.Retry shortly.