> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/objects/records/records-apis/lookup-record-api.md).
# Lookup Record API
{% hint style="success" %}
**Audience:** Developers and Solution Architects
**Purpose:** Explains how to use the Lookup space.vars.entity API to retrieve space.vars.entities by name or email and resolve external identifiers into stable space.vars.entity IDs for integration workflows.
{% endhint %}
## Overview
Use the **Lookup Record** endpoint to retrieve an existing space.vars.entity using a human-readable identifier instead of a system-generated record ID.
This supports integration workflows that must resolve space.vars.entities dynamically before performing ID-based operations. Different space.vars.entity 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](/docs/concepts/objects/records/records-core-concepts.md) and the [Records Data Model](/docs/concepts/objects/records/records-data-model.md).
### Why Use This API
You can use the Lookup space.vars.entity API when you need to:
* Resolve a space.vars.entity by name or email before performing additional operations
* Synchronize data from external systems that store business identifiers
* Validate whether a space.vars.entity exists before creating a new one
* Support upsert-style workflows
* Resolve identifiers during data migration
Lookup space.vars.entity operations are typically used before calling ID-based endpoints such as update, patch, archive, or delete. Once a space.vars.entity ID is known, ID-based operations are preferred. Unlike the Search API, which supports flexible filtering and may return multiple results, the Lookup space.vars.entity API is designed to retrieve a single space.vars.entity based on a unique identifier.
### Lookup Record API Behavior
Use this endpoint to resolve a space.vars.entity by its lookup identifier and return the corresponding space.vars.entity data when a match exists. It:
* Returns the matching space.vars.entity when a valid space.vars.entity name or email identifier exists within the specified space.vars.object
* Returns a not-found result when no matching space.vars.entity exists
* Does not create new space.vars.entities
* Enforces space.vars.object-level uniqueness constraints
* Uses record name for most space.vars.objects and email for space.vars.contact space.vars.entities
* 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](https://app.go.kizen.com/api/docs/public/swagger#/records/records_lookup_retrieve) docs.
## GET /api/records/{object\_identifier}/lookup
> Get entity record by name or email
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"EntityRecordDetail":{"type":"object","properties":{"object_type":{"type":"string"},"num_upcoming_activities":{"type":"integer"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"num_associated_team_members":{"type":"integer"},"lead_source_types":{"type":"array","items":{"$ref":"#/components/schemas/LeadSourceType"}}},"required":["access","client_info","fields","id","lead_source_types","num_associated_team_members","num_upcoming_activities","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]},"LeadSourceType":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/ValueEnum"},"label":{"type":"string"}},"required":["label","value"]},"ValueEnum":{"enum":["organic_search","direct_traffic","site_referral","facebook_ads","google_ads","social","paid_social","utm","custom"],"type":"string","description":"* `organic_search` - Organic Search\n* `direct_traffic` - Direct Traffic\n* `site_referral` - Site Referral\n* `facebook_ads` - Facebook Ads\n* `google_ads` - Google Ads\n* `social` - Social\n* `paid_social` - Paid Social\n* `utm` - UTM\n* `custom` - Custom"}}},"paths":{"/api/records/{object_identifier}/lookup":{"get":{"operationId":"records_lookup_retrieve","description":"Get entity record by name or email","parameters":[{"in":"query","name":"all_fields","schema":{"type":"boolean"},"description":"Return all fields."},{"in":"query","name":"field_ids","schema":{"type":"string"},"description":"Comma separated field ids to include in response. If present but empty, it will return default fields only."},{"in":"query","name":"field_names","schema":{"type":"string"},"description":"Comma separated field names to include in response. If present but empty, it will return default fields only."},{"in":"query","name":"identifier","schema":{"type":"string"},"description":"Entity record name or contact email","required":true},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true}],"tags":["records"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordDetail"}}},"description":""}}}}}}
```
### Lookup Record Schema
## The EntityRecordDetail object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordDetail":{"type":"object","properties":{"object_type":{"type":"string"},"num_upcoming_activities":{"type":"integer"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"num_associated_team_members":{"type":"integer"},"lead_source_types":{"type":"array","items":{"$ref":"#/components/schemas/LeadSourceType"}}},"required":["access","client_info","fields","id","lead_source_types","num_associated_team_members","num_upcoming_activities","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]},"LeadSourceType":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/ValueEnum"},"label":{"type":"string"}},"required":["label","value"]},"ValueEnum":{"enum":["organic_search","direct_traffic","site_referral","facebook_ads","google_ads","social","paid_social","utm","custom"],"type":"string","description":"* `organic_search` - Organic Search\n* `direct_traffic` - Direct Traffic\n* `site_referral` - Site Referral\n* `facebook_ads` - Facebook Ads\n* `google_ads` - Google Ads\n* `social` - Social\n* `paid_social` - Paid Social\n* `utm` - UTM\n* `custom` - Custom"}}}}
```
***
## What’s Next
After retrieving a space.vars.entity by lookup, you can:
* Use ID-based endpoints to update, patch, archive, or modify the space.vars.entity
* Use the Upsert API to conditionally create or update space.vars.entities
* Create a new space.vars.entity when no existing match is found
* Reference the returned space.vars.entity ID for subsequent operations
* Incorporate lookup workflows into schema-aware integrations
For more information on space.vars.entity operations, see the related space.vars.entities API topics below:
Related Topics
* [Add Records API](/docs/concepts/objects/records/records-apis/add-records-api.md)
* [Manage Records by ID API](/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md)
* [Search Records API](/docs/concepts/objects/records/records-apis/search-records-api.md)
* [Create or Update Records (Upsert) API](/docs/concepts/objects/records/records-apis/create-or-update-records-upsert-api.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.kizen.com/docs/concepts/objects/records/records-apis/lookup-record-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.