---
updatedAt: 2026-04-08T10:25:03.000Z
---

# 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 <nqrana@us.acoustic.com> AND the account id 9999:
/databases/{databaseId}/contacts?filter=keyFields=email=<nqrana@us.acoustic.com>;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

[block:code]
{
  "codes": [
    {
      "code": "\"meta\": {\n    \"attributes\": {},\n    \"generalErrors\": [],\n    \"fieldErrors\": {},\n    \"links\": [],\n    \"nextPageUrl\": null\n  },\n  \"data\": [\n    {\n      \"lastModifiedDate\": \"2017-06-14T00:15:31.000+00:00\",\n      \"email\": \"john@sp.com\",\n      \"optInDetails\": \"User Name: sarah_hydreigon@silverpop.com. IP Address: 32.97.110.59\",\n      \"optOutDetails\": \"\",\n      \"emailType\": \"HTML\",\n      \"customFields\": [\n        {\n          \"name\": \"Android_ID\",\n          \"value\": \"12345\"\n        },\n        {\n          \"name\": \"Business_Account\",\n          \"value\": \"12345\"\n        },\n        {\n          \"name\": \"Company\",\n          \"value\": \"Acoustic\"\n        },\n        {\n          \"name\": \"First_Name\",\n          \"value\": \"John\"\n        },\n        {\n          \"name\": \"Frequent_Flyer\",\n          \"value\": \"12345\"\n        },\n        {\n          \"name\": \"Loyalty_Card\",\n          \"value\": \"12345\"\n        }\n      ],\n      \"createdFrom\": \"IMPORT\",\n      \"optedOutDate\": null,\n      \"leadSource\": null,\n      \"optInDate\": \"2017-06-13T23:58:24.000+00:00\"\n    }\n  ]\n}",
      "language": "text"
    }
  ]
}
[/block]

Sample Error Codes

[block:parameters]
{
  "data": {
    "h-0": "Scenario",
    "h-1": "Code",
    "h-2": "Error Message",
    "0-0": "Invalid Database ID",
    "0-1": "404",
    "0-2": "Database not found",
    "1-0": "Invalid Lookup Key field",
    "1-1": "404",
    "1-2": "Field not found",
    "2-0": "Invalid Lookup Key value",
    "2-1": "404",
    "2-2": "No contact found",
    "3-0": "No contact matches all Lookup Key values",
    "3-1": "404",
    "3-2": "No contact found",
    "4-0": "More than 5 Lookup Key pairs provided in the request",
    "4-1": "404",
    "4-2": "Lookup keys count greater than five",
    "5-0": "Field provided is not a Lookup Key field",
    "5-1": "404",
    "5-2": "Lookup key not found"
  },
  "cols": 3,
  "rows": 6
}
[/block]