Lookup Record API

Audience: Developers and Solution Architects

Purpose: Explains how to use the Lookup Record API to retrieve Records by name or email and resolve external identifiers into stable Record IDs for integration workflows.

Overview

Use the Lookup Record endpoint to retrieve an existing Record using a human-readable identifier instead of a system-generated record ID.

This supports integration workflows that must resolve Records dynamically before performing ID-based operations. Different Record types use different lookup identifiers, and those identifiers must be unique within the Object.

The material on this page builds on information covered in Records Core Concepts and the Records Data Model.

Why Use This API

You can use the Lookup Record API when you need to:

• Resolve a Record by name or email before performing additional operations

• Synchronize data from external systems that store business identifiers

• Validate whether a Record exists before creating a new one

• Support upsert-style workflows

• Resolve identifiers during data migration

Lookup Record operations are typically used before calling ID-based endpoints such as update, patch, archive, or delete. Once a Record ID is known, ID-based operations are preferred. Unlike the Search API, which supports flexible filtering and may return multiple results, the Lookup Record API is designed to retrieve a single Record based on a unique identifier.

Lookup Record API Behavior

Use this endpoint to resolve a Record by its lookup identifier and return the corresponding Record data when a match exists. It:

• Returns the matching Record when a valid Record name or email identifier exists within the specified Object

• Returns a not-found result when no matching Record exists

• Does not create new Records

• Enforces Object-level uniqueness constraints

• Uses record name for most Objects and email for Contact Records

• Performs case-insensitive matching on lookup identifiers

  Strips leading, trailing, and duplicate whitespace before evaluating the lookup value

• Respects permission constraints configured for the requesting user context

• Returns a response structured according to the Records Data Model schema

---

Lookup Record Endpoint

Want to try the API out? Visit our Swagger docs.

get

Get entity record by name or email

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_identifierstringRequired

Query parameters

all_fieldsbooleanOptional

Return all fields.

field_idsstringOptional

Comma separated field ids to include in response. If present but empty, it will return default fields only.

field_namesstringOptional

Comma separated field names to include in response. If present but empty, it will return default fields only.

identifierstringRequired

Entity record name or contact email

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

get

/api/records/{object_identifier}/lookup

HTTPcURLJavaScriptPython

GET /api/records/{object_identifier}/lookup?identifier=text HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Accept: */*

200Success

{
  "object_type": "string",
  "num_upcoming_activities": 0,
  "fields": {},
  "id": "18ff12e2-c4a0-4000-89e6-9b216dd9d801",
  "num_associated_team_members": 0,
  "client_info": {
    "num_addresses_v2": 0,
    "display_name": "string",
    "email_on_suppression_list": false
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "first_lead_source": {
    "id": "18ff12e2-c4a0-4000-8e84-0f8bb0dafb01",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8dda-0175712cda01",
    "custom_object_record": "18ff12e2-c4a0-4000-831e-88c0810f2401",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "last_lead_source": {
    "id": "18ff12e2-c4a0-4000-8fe9-71a84bc6c101",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8803-a33e719dc801",
    "custom_object_record": "18ff12e2-c4a0-4000-8c84-44d6dd2b6f01",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "lead_source_types": [
    {
      "value": "organic_search",
      "label": "string"
    }
  ]
}

Lookup Record Schema

---

What’s Next

After retrieving a Record by lookup, you can:

• Use ID-based endpoints to update, patch, archive, or modify the Record

• Use the Upsert API to conditionally create or update Records

• Create a new Record when no existing match is found

• Reference the returned Record ID for subsequent operations

• Incorporate lookup workflows into schema-aware integrations

For more information on Record operations, see the related Records API topics below:

Related Topics

• Add Records API

• Manage Records by ID API

• Search Records API

• Create or Update Records (Upsert) API