HomeSandbox AccountsAPIApp StudioWebhooksCommunity
API

List, search, and filter contacts

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

The read behind the Contacts page. It finds contacts by list (listid), tag (tagid, or filters[tagName] for a tag name), list status (status), text (search matches name, email, phone and account name), segment (segmentid), form (formid), automation (seriesid), or created and updated date (filters[created_after], filters[created_before], filters[updated_after], filters[updated_before]). Filters combine, except that while segmentid is set only status and search still apply and the other filters are ignored, and tagid and filters[tagName] cannot be sent together. GET /contactTags and GET /contactLists return association rows, not contacts. Use only the query parameters documented here: unsupported filter and order fields are silently ignored, so the response looks filtered but is not. The API spellings firstName, lastName and owner are accepted as filter keys, but order keys take only the column spellings: orders[lastName] is ignored, orders[last_name] works. Results are paginated: limit defaults to 20 and is capped at 100; page with offset, or walk a large set with id_greater. Results come back sorted by email ascending unless an orders[...] key says otherwise. To fetch one contact by id, use GET /contacts/{id}. To count the contacts a query matches without fetching records, send meta=only and read meta.total. There is no filter on when a contact's list status changed: filters[updated_after] and filters[updated_before] use the contact record's last-modified date (udate). That date moves on any save of the record, including a PUT /contacts/{id} that changes nothing, and, through database triggers, on list, tag, custom field, score, note and task changes, however they are made. A window on it counts every contact touched in that window, not the contacts whose status changed, so it over-counts new unsubscribes or bounces. A count filtered only by status on an account with millions of contacts scans every contact and can take longer than ten seconds. Archived contacts, the contacts that have been deleted, are never returned whatever the status value; list them with GET /contactArchives.

🚧

Organization-Related Nodes Have Been Deprecated

Contact-Organization relationships are now managed through Account-Contact end points

👍

Performance Tip for Pagination

Accounts with many Contacts may encounter slower responses when using the offset parameter to paginate with this endpoint. For best performance sort using orders[id]=ASC and use the id_greater parameter to paginate. This is especially important when calling this endpoint frequently, such as when retrieving many or all Contacts from an account.

Note that when using the segmentid parameter, best performance will be achieved by: paginating using the offset parameter and not using any orders parameter.

{
   "contacts":[
      {
         "cdate":"2017-01-25T23:58:14-06:00",
         "email":"[email protected]",
         "phone":"3120000000",
         "firstName":"John",
         "lastName":"Doe",
         "orgid":"0",
         "segmentio_id":"",
         "bounced_hard":"0",
         "bounced_soft":"0",
         "bounced_date":"0000-00-00",
         "ip":"0",
         "ua":"",
         "hash":"31e076c964f4262817f9ba302c96e1c6",
         "socialdata_lastcheck":"0000-00-00 00:00:00",
         "email_local":"",
         "email_domain":"",
         "sentcnt":"0",
         "rating_tstamp":"0000-00-00",
         "gravatar":"3",
         "deleted":"0",
         "adate":"2017-02-22 15:26:24",
         "udate":"2017-01-25T23:58:14-06:00",
         "edate":"2017-01-27 14:44:13",
         "scoreValues":[

         ],
         "links":{
            "bounceLogs":"https://:account.api-us1.com/api/:version/contacts/68/bounceLogs",
            "contactAutomations":"https://:account.api-us1.com/api/:version/contacts/68/contactAutomations",
            "contactData":"https://:account.api-us1.com/api/:version/contacts/68/contactData",
            "contactGoals":"https://:account.api-us1.com/api/:version/contacts/68/contactGoals",
            "contactLists":"https://:account.api-us1.com/api/:version/contacts/68/contactLists",
            "contactLogs":"https://:account.api-us1.com/api/:version/contacts/68/contactLogs",
            "contactTags":"https://:account.api-us1.com/api/:version/contacts/68/contactTags",
            "contactDeals":"https://:account.api-us1.com/api/:version/contacts/68/contactDeals",
            "deals":"https://:account.api-us1.com/api/:version/contacts/68/deals",
            "fieldValues":"https://:account.api-us1.com/api/:version/contacts/68/fieldValues",
            "geoIps":"https://:account.api-us1.com/api/:version/contacts/68/geoIps",
            "notes":"https://:account.api-us1.com/api/:version/contacts/68/notes",
            "organization":"https://:account.api-us1.com/api/:version/contacts/68/organization",
            "plusAppend":"https://:account.api-us1.com/api/:version/contacts/68/plusAppend",
            "trackingLogs":"https://:account.api-us1.com/api/:version/contacts/68/trackingLogs",
            "scoreValues":"https://:account.api-us1.com/api/:version/contacts/68/scoreValues"
         },
         "id":"68",
         "organization":null
      },
      {
         "cdate":"2017-02-09T12:14:58-06:00",
         "email":"[email protected]",
         "phone":"",
         "firstName":"Aaron",
         "lastName":"Allen",
         "orgid":"14",
         "segmentio_id":"",
         "bounced_hard":"0",
         "bounced_soft":"0",
         "bounced_date":"0000-00-00",
         "ip":"0",
         "ua":"",
         "hash":"31b92c033c3e55de6d9eb9c44ee1bfa5",
         "socialdata_lastcheck":"0000-00-00 00:00:00",
         "email_local":"",
         "email_domain":"",
         "sentcnt":"0",
         "rating_tstamp":"0000-00-00",
         "gravatar":"1",
         "deleted":"0",
         "adate":"2017-03-16 13:18:12",
         "udate":"2017-02-09T12:14:58-06:00",
         "edate":"0000-00-00 00:00:00",
         "scoreValues":[

         ],
        "accountContacts": [
            "1"
         ],
         "links":{
            "bounceLogs":"https://:account.api-us1.com/api/:version/contacts/73/bounceLogs",
            "contactAutomations":"https://:account.api-us1.com/api/:version/contacts/73/contactAutomations",
            "contactData":"https://:account.api-us1.com/api/:version/contacts/73/contactData",
            "contactGoals":"https://:account.api-us1.com/api/:version/contacts/73/contactGoals",
            "contactLists":"https://:account.api-us1.com/api/:version/contacts/73/contactLists",
            "contactLogs":"https://:account.api-us1.com/api/:version/contacts/73/contactLogs",
            "contactTags":"https://:account.api-us1.com/api/:version/contacts/73/contactTags",
            "contactDeals":"https://:account.api-us1.com/api/:version/contacts/73/contactDeals",
            "deals":"https://:account.api-us1.com/api/:version/contacts/73/deals",
            "fieldValues":"https://:account.api-us1.com/api/:version/contacts/73/fieldValues",
            "geoIps":"https://:account.api-us1.com/api/:version/contacts/73/geoIps",
            "notes":"https://:account.api-us1.com/api/:version/contacts/73/notes",
            "organization":"https://:account.api-us1.com/api/:version/contacts/73/organization",
            "plusAppend":"https://:account.api-us1.com/api/:version/contacts/73/plusAppend",
            "trackingLogs":"https://:account.api-us1.com/api/:version/contacts/73/trackingLogs",
            "scoreValues":"https://:account.api-us1.com/api/:version/contacts/73/scoreValues"
         },
         "id":"73",
         "organization":"14"
      }
   ],
   "meta":{
      "total":"2",
      "page_input":{
         "segmentid":null,
         "formid":0,
         "listid":0,
         "tagid":0,
         "limit":20,
         "offset":0,
         "search":null,
         "sort":null,
         "seriesid":0,
         "waitid":0,
         "status":-1,
         "forceQuery":0,
         "cacheid":"895202850f4ca4144513c0962812f951"
      }
   }
}
Query Params
string

Return only the contacts with these ids. Pass a comma-separated list (ids=1,2,42) or repeat the key (ids[]=1&ids[]=2). The response returns at most as many contacts as ids given.

integer
≤ 100
Defaults to 20

Number of contacts to return per request. Defaults to 20; the maximum is 100, and asking for more is capped at 100.

integer
Defaults to 0

Number of contacts to skip before returning results. Use with limit to page through contacts. For walking a large set, filtering with id_greater is more reliable than a growing offset.

string
enum

Set to only to return just the metadata (such as the total count) with no contact records, or to omit to leave the metadata out of the response.

Allowed:
string

Email address of the contact you want to get

string

Filter contacts that contain the given value in the email address

int32

Exclude the contact with the given ID from the response. Can be repeated to exclude multiple IDs: exclude[]=1&exclude[]=2.

int32

Filter contacts associated with the given form

int32

Only include contacts with an ID greater than the given ID

int32

Only include contacts with an ID less than the given ID

string

Filter contacts associated with the given list

string

Filter contacts whose stored phone number starts with the given value, compared against the string exactly as stored, including country code, spaces, and punctuation (for example +1 555-555-5555). If the stored format is unknown, use search with one segment of the number (for example 5555) instead. A differently formatted phone value returns no matches, and search matches segments of the stored format (or a prefix of the last segment) but never a run of digits with the formatting stripped.

int32

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

integer

Filter contacts that belong to the given account, by account id. Equivalent to organization.

Search contacts. A full email address matches the contact's email exactly; any other value is matched against email, first name, last name, phone, and account name. q is accepted as an alias. When search is set it takes precedence over email_like and filters[email_hash].

int32

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)

int32

Filter contacts associated with the given automation

integer
enum

Only used together with seriesid. Set to 1 to return only contacts that finished the automation, or 0 for contacts that entered it but have not finished.

Allowed:
integer

Only used together with seriesid. Return only contacts that hit the given conversion while they were in the automation.

int32
enum
Defaults to -1

Filter contacts by list-membership status: -1 any (the default), 0 unconfirmed, 1 active, 2 unsubscribed, 3 bounced. Combine with listid to check the status on one list. Values above 3 match nothing and return an empty result with total 0 rather than an error; values below -1 behave as "on at least one list, any status" (or "on the given listid, any status" when listid is set); a non-numeric value is read as 0 (unconfirmed).

Allowed:
int32

Filter contacts associated with the given tag

date

Filter contacts that were created prior to this date

date

Filter contacts that were created after this date

date

Contacts whose record was last modified before this date. The last-modified date moves on any save of the contact record and, through database triggers, on list, tag, custom field, score, note and task changes however they are made, so it is not the date a list status changed and a window on it includes every contact touched for any reason. The time a contact left a list is udate on its list membership (GET /contacts/{id}/contactLists), which cannot be filtered on.

date

Contacts whose record was last modified after this date. The last-modified date moves on any save of the contact record and, through database triggers, on list, tag, custom field, score, note and task changes however they are made, so it is not the date a list status changed: a window on it includes every contact touched in that window for any reason. There is no filter for when a contact unsubscribed or bounced; that time is udate on the contact's list membership (GET /contacts/{id}/contactLists), which cannot be filtered on.

string

Filter by exact contact id. To fetch several known contacts at once, prefer the ids parameter.

string

Filter by exact email address. Equivalent to the email parameter.

string

Filter contacts created at exactly the given date and time. For a range, use filters[created_before] and filters[created_after].

string

Filter contacts last updated at exactly the given date and time. For a range, use filters[updated_before] and filters[updated_after].

string

Filter contacts by the hash of their email address (the hash field returned on the contact). The top-level email_hash parameter is a deprecated alias. Ignored when search is supplied.

string

Filter contacts by tag name instead of tag id. Accepts one tag name or a list (filters[tagName][]=a&filters[tagName][]=b); a contact matches if it has any of the tags. Cannot be combined with tagid. Unknown tag names are rejected with a 400 error.

string

Filter contacts by custom field value, for example filters[fields][5]=blue. Repeat with different field ids to require all of them at once. On single-value fields the value matches from the start of the stored value; on multi-select fields (listbox, checkbox) it matches anywhere. An empty value matches contacts with a blank or missing value. Unknown field ids are rejected with a 400 error.

string

Filter contacts whose first name is exactly the given value. Also accepted as filters[firstName].

string

Filter contacts whose last name is exactly the given value. Also accepted as filters[lastName].

string

Filter contacts owned by the given user, by user id. Also accepted as filters[owner].

string

Filter contacts whose account (organization) name is exactly the given value. Also accepted as filters[customer_acct_name].

int32

Filter by contacts in the wait queue of an automation block

string
enum
Defaults to asc

Order contacts by unique ID

Allowed:
string
enum

Order contacts by creation date

Allowed:
string
enum
Defaults to asc

Order contacts by last-updated date

Allowed:
string
enum
Defaults to asc

Order contacts by email

Allowed:
string
enum

Order contacts by first name

Allowed:
string
enum

Order contacts by last name

Allowed:
string
enum

Order contacts by full name. Applied as first name then last name, both in the given direction.

Allowed:
string
enum

Order contacts by score. Send the score id in sortId: each contact is then ranked by its highest value for that score, and contacts without one come last. sortId is not enforced. Without it the query joins every score value a contact has, which is slow on large accounts, drops contacts that have no score value, and can list a contact once per score value. orders[contactScoreValue] and orders[score_recent] are not order keys and are silently ignored.

Allowed:
string
enum
Defaults to asc

Order contacts by contact owner (user id)

Allowed:
string
enum
Defaults to asc

Order contacts by the name of the account they belong to

Allowed:
string
enum
Defaults to asc

Order contacts by the value of a custom field. Use asc or desc and pass the custom field id in the sortId parameter.

Allowed:
string

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

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:
number

Id of the score (with orders[score]) or custom field (with orders[field]) to sort by. orders[field] is ignored without it; orders[score] still runs without it, see that parameter.

string

Alias for search; prefer search. When both are sent, q is used for the text search. Only search switches off email_like and filters[email_hash], and only search is applied inside a segment (segmentid) query; q is not.

string
enum

Shortcut for ordering by full name: sort=name orders contacts by first name, then last name, both ascending. Ignored when any orders[...] parameter is sent. For every other ordering, and for descending order, use the orders[...] parameters.

Allowed:
string

Used only together with email_like, and only when search is empty; on its own it does nothing. A contact then matches when its email contains the part of email_like before the @, or when its first and last name equal the first two words of name (name=Sam Example matches first name Sam and last name Example).

string

Older quick search kept for existing callers; prefer search. Matches contacts whose full name (first and last name joined by a space) or email contains the value anywhere. Applied even when search is also sent.

string

Like nameOrEmailLike, and also matches when the phone number contains the value anywhere. Prefer search.

Responses

Updated 2 months ago

Did this page help you?
Language
Credentials
Header
URL
LoadingLoading…
Response
Choose an example:
application/json

Updated 2 months ago

Did this page help you?