HomeSandbox AccountsAPI DocumentationApp StudioWebhooksCommunity
API Documentation
Start typing to search…

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

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.

{
   "contacts":[
      {
         "cdate":"2017-01-25T23:58:14-06:00",
         "email":"janedoe@example.com",
         "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":"aaronallen@example.com",
         "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

int32
Defaults to null

Return only contacts that match a list segment (the first call kicks off an asynchronous query. When the query is complete, subsequent API calls 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
Defaults to ASC

Order contacts by unique ID

string

Order contacts by creation date

string
Defaults to ASC

Order contacts by email

string

Order contacts by first name

string

Order contacts by last name

string

Order contacts by full name

string

Order contacts by score

string

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

Responses

Updated 5 months ago

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

Updated 5 months ago

Did this page help you?