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.


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


  • 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}/contacts?filter=keyFields=email=[email protected];accountId=9999


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:",
      "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

ScenarioCodeError Message
Invalid Database ID404Database not found
Invalid Lookup Key field404Field not found
Invalid Lookup Key value404No contact found
No contact matches all Lookup Key values404No contact found
More than 5 Lookup Key pairs provided in the request404Lookup keys count greater than five
Field provided is not a Lookup Key field404Lookup key not found