GET contact by lookup key

Use this this REST API to retrieve data for contact(s) with the given lookup key filter(s) from the database. You can return up to 5 contacts that match the Lookup Key filters provided in the request call.

Prerequisites

These prerequisites are required in order to use this REST API:

  • Grant user access to Oauth application from Organizational Settings.
  • Generate Refresh Token for Oauth application from Organizational Settings.
  • Generate Access Token in order to call the Contact by Lookup Key REST API.

Input parameters

Database ID (from the list of databases, hover over the database name to get the database ID).

Filters

  • Up to 5 different filters can be used.
  • Flexible (non-keyed) databases: filters must be email address or a lookup key field.
  • Restricted (keyed) databases: filters must be key fields.

Sample Request

This request will look for a contact with the email [email protected] AND the account id 9999:
/databases/{databaseId}/[email protected];accountId=9999

Response

The response will return all system fields plus an array of all current database fields and their corresponding values for the matching contact.

Sample Response for Successful Call

"meta": {
    "attributes": {},
    "generalErrors": [],
    "fieldErrors": {},
    "links": [],
    "nextPageUrl": null
  },
  "data": [
    {
      "lastModifiedDate": "2017-06-14T00:15:31.000+00:00",
      "email": "[email protected]",
      "optInDetails": "User Name: [email protected] IP Address: 32.97.110.59",
      "optOutDetails": "",
      "emailType": "HTML",
      "customFields": [
        {
          "name": "Android_ID",
          "value": "12345"
        },
        {
          "name": "Business_Account",
          "value": "12345"
        },
        {
          "name": "Company",
          "value": "Acoustic"
        },
        {
          "name": "First_Name",
          "value": "John"
        },
        {
          "name": "Frequent_Flyer",
          "value": "12345"
        },
        {
          "name": "Loyalty_Card",
          "value": "12345"
        }
      ],
      "createdFrom": "IMPORT",
      "optedOutDate": null,
      "leadSource": null,
      "optInDate": "2017-06-13T23:58:24.000+00:00"
    }
  ]
}

Sample Error Codes

Scenario

Code

Error Message

Invalid Database ID

404

Database not found

Invalid Lookup Key field

404

Field not found

Invalid Lookup Key value

404

No contact found

No contact matches all Lookup Key values

404

No contact found

More than 5 Lookup Key pairs provided in the request

404

Lookup keys count greater than five

Field provided is not a Lookup Key field

404

Lookup key not found