GET Contact by Lookup Key REST API

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 AND the account id 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": "",
      "optInDetails": "User Name: IP Address:",
      "optOutDetails": "",
      "emailType": "HTML",
      "customFields": [
          "name": "Android_ID",
          "value": "12345"
          "name": "Business_Account",
          "value": "12345"
          "name": "Company",
          "value": "IBM"
          "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

11 comments on"GET Contact by Lookup Key REST API"

  1. Roman Kovařík February 01, 2018

    Is it possible to get a contact by visitor_key (web tracking cookie value)? I known it possible trough the XML API.

    • Hello Roman,
      Just to clarify, are you asking if there is another way besides using XML API to get visitor_key (web tracking cookie value)?

      Thank you,

  2. Hello, how do I retrieve the contactId or recipientId by GET Contact by Lookup Key REST API?

    • Hello Andy,
      Please let me know if the below helps.

      Thank you

      Implementation Notes
      Use this API to retrieve contact representation(s) from a given databaseId for the given lookup key filter(s)

      Response Class
      ModelModel Schema
      Contact {
      email (String, optional): A Contact’s email address,
      emailType (String, optional): The type of email to send to a contact- HTML or TEXT,
      leadSource (String, optional): The lead source for a Contact,
      optInDetails (String, optional): The Opt In Details of a Contact; can only be set on a Contact being added!,
      customFields (Array[customFieldSchema], optional): A list of Custom Field Values
      customFieldSchema {
      name (String): name of the custom field.,
      value (String): value of the custom field.

      Response Content Type
      Parameter Value Description Parameter Type Data Type
      ID of the Database from which to return a Contact path long
      Contact lookup key filter(s) (e.g., lookupkeyfields=FieldName1=value;FieldName2=value) query string

      • RecipientID is not available in the response from the API request when doing a search with lookup key like email. Is there a way to find retrieve that recipientID when it´s unknown and the only known information is the contact email?


        • Hello Mikael,
          I am gathering this info for you and will get back to you as soon as I have it.

          Thank you

        • Hello Mikael,
          Currently not possible with any Rest API. You can still use SelectRecipientData XML API to get back the RecipientId.

          Thank you,

          • Is it still not possible to fetch the contactId/recipientId using the REST api? It’d be very useful if the /databases/{databaseId}/contacts endpoint returned it when filtered by custom fields.

  3. Philippe Damoune October 24, 2018

    Hi JREllis,

    Is it possible to get all the contacts of a database or a query, … (or at least, their recipient id) ? (REST or XML)

  4. Hi,

    How to add contacts in the sms database through API, i mean which API i need to call can you please explain..


Join The Discussion

Your email address will not be published. Required fields are marked *