HomeSandbox AccountsAPIApp StudioWebhooksCommunity
API

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.

🚧

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

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

string

Filter contacts that contain the given value in the email address

int32

Exclude from the response the contact with the given ID

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 where the phone number starts with the given value

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

string
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)

int32

Filter contacts associated with the given automation

int32
Defaults to -1

See available values

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

Filter contacts that were updated before this date

date

Filter contacts that were updated after this date

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

Allowed:
string
enum

Order contacts by score. Must be used in conjunction with 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

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

Responses

Updated 8 months ago

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

Updated 8 months ago

Did this page help you?