List, search, and filter contacts

get

https://{youraccountname}.api-us1.com/api/3/contacts

Use this API endpoint to list all contacts, search contacts, or filter contacts by many criteria. For example, search for specific contacts by email, list, account.

Query Params

ids

string

Filter contacts by ID. Can be repeated for multiple IDs. Example: ids[]=1&ids[]=2&ids[]=42

string

Email address of the contact you want to get

email_like

string

Filter contacts that contain the given value in the email address

exclude

int32

Exclude from the response the contact with the given ID

formid

int32

Filter contacts associated with the given form

id_greater

int32

Only include contacts with an ID greater than the given ID

id_less

int32

Only include contacts with an ID less than the given ID

listid

string

Filter contacts associated with the given list

phone

string

Filter contacts where the phone number starts with the given value

organization

int32

(Deprecated) Please use Account-Contact end points. Filter contacts associated with the given organization ID

string

Defaults to null

Filter contacts that match the given value in the contact names, organization, phone or email

segmentid

int32

Defaults to null

Return only contacts that match a list segment. The first API call within 1 hour or an API call with the param forceQuery=1 will kick off an new segment request. When the segment results are ready, subsequent API calls without the forceQuery param will return contacts that match the segment - timeout 1hr)

seriesid

int32

Filter contacts associated with the given automation

status

int32

Defaults to -1

See available values

tagid

int32

Filter contacts associated with the given tag

filters[created_before]

date

Filter contacts that were created prior to this date

filters[created_after]

date

Filter contacts that were created after this date

filters[updated_before]

date

Filter contacts that were updated before this date

filters[updated_after]

date

Filter contacts that were updated after this date

waitid

int32

Filter by contacts in the wait queue of an automation block

orders[id]

string

enum

Defaults to ASC

Order contacts by unique ID

Allowed:

orders[cdate]

string

enum

Order contacts by creation date

Allowed:

orders[email]

string

enum

Defaults to ASC

Order contacts by email

Allowed:

orders[first_name]

string

enum

Order contacts by first name

Allowed:

orders[last_name]

string

enum

Order contacts by last name

Allowed:

orders[name]

string

enum

Order contacts by full name

Allowed:

orders[score]

string

enum

Order contacts by score. Must be used in conjunction with the sortId parameter

Allowed:

in_group_lists

string

Set this to "true" in order to return only contacts that the current user has permissions to see.

forceQuery

number

enum

Defaults to 0

If present and equal to 1, a new segment request is kicked off which will return an updated result set. Otherwise, a segmented API request with a consistent sorting will return the same results for 1 hour. Note that re-ordering the results will also cause an updated result set to be returned.

Allowed:

sortId

number

If sorting results by a score or custom field, this parameter holds the id of the score or custom field respectively

Responses

200200

400400