List contacts

get

https://api.omnisend.com/api/contacts

Returns a paginated list of contacts filtered by the provided query parameters.

Scopes:
contacts.read

Rate Limiting:
This endpoint is rate limited to 400 requests per minute.

Filter restrictions:

tag and status cannot be used together in the same request.
updatedAtFrom cannot be combined with email, phone, status, segmentID, or tag.

Query Params

limit

integer

1 to 250

Number of items per page. Range: 1-250. Default: 100

after

string

Opaque cursor for fetching the next page (from paging.cursors.after)

before

string

Opaque cursor for fetching the previous page (from paging.cursors.before)

sort

string

enum

Sort field. Default: createdAt

Allowed:

direction

string

enum

Sort direction. Default: desc

Allowed:

string

Filter by email address

phone

string

Filter by phone number

status

string

enum

Contact subscription status filter. Cannot be combined with tag

Allowed:

segmentID

string

Filter by segment ID

tag

string

Filter by tag. Cannot be combined with status

updatedAtFrom

string

Filter contacts updated at or after this RFC3339 timestamp. Cannot be combined with email, phone, status, segmentID, or tag

Headers

Omnisend-Version

string

required

Defaults to 2026-03-15

API version that specifies the response format and behaviour

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK

400Request contains invalid or missing fields

401Authentication is missing or invalid

403Insufficient permissions for this operation

410API version has been retired

429Rate limit exceeded

500Unexpected error occurred