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 entity record by name or email
Return all fields.
Comma separated field ids to include in response. If present but empty, it will return default fields only.
Comma separated field names to include in response. If present but empty, it will return default fields only.
Entity record name or contact email
GET /api/records/{object_identifier}/lookup?identifier=text HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Accept: */*
{
"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:
Last updated
Was this helpful?