Manage Records by ID API
Audience: Developers and Solution Architects
Purpose: Explains how to use ID-based record management APIs to retrieve, update, partially update, archive, and manage paginated field values while enforcing validation, permissions, and lifecycle controls.
Overview
Use the Manage Records by ID endpoints to retrieve, update, partially update, and archive existing Records using their system-generated record IDs. You can use them to operate on a specific Record’s current state, apply full or targeted changes, and manage lifecycle actions while preserving audit history.
These endpoints are designed for precise, ID-based Record management. They enable external systems to synchronize Record updates, enforce consistent data control, and retrieve paginated field values when selectable option sets are too large to return inline without relying on mutable business identifiers such as Record name or email.
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 Managing Records by ID endpoints when you need to:
Synchronize Record updates from an external system into Kizen
Retrieve the current state of a Record before applying changes
Update Record field values in response to lifecycle events
Apply targeted updates without sending a full Record payload
Archive Records that are no longer active but must remain auditable
Retrieve paginated selectable field values when option sets are too large to return inline
ID-based endpoints provide deterministic Record control and are recommended once the Record ID is known.
Manage Records by ID API Behavior
Use these endpoints to retrieve, modify, and manage Records using a system-generated Record ID. They:
GET retrieves a Record and returns its current field values; use when evaluating the current Record state before applying changes
PUT updates a Record using a full update pattern; use when replacing the complete Record payload
PATCH updates specific fields without replacing the full Record payload; use for targeted changes
DELETE archives a Record while preserving stored data and audit history
GET (Field Values List) returns a paginated set of selectable values when option sets are too large to return inline in the Record detail response
All operations respect validation rules, permission constraints, and Object-level configuration.
Manage Records by ID Endpoints
The following endpoints are included in the Managing Records by ID capability set:
Retrieve a Record (GET)
Want to try the API out? Visit our Swagger docs.
Get entity record by ID
^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$Include summary data in the response, including lead sources.
Comma separated category ids, to filter by field category. Ignored when field_ids is present.
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.
Include hidden fields in the response.
GET /api/records/{object_identifier}/{entity_id} 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"
}
]
}Update a Record (PUT)
Want to try the API out? Visit our Swagger docs.
Update entity record
^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$Updates the identifier of matching archived record to not raise a conflict.
overwrite- overwrite
overwrite- overwrite
PUT /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 804
{
"fields": [
{
"id": "<integer_field_id>",
"value": 100
},
{
"id": "<primary_field_id>",
"value": "<record_id>"
},
{
"id": "<primary_field2_id>",
"value": {
"id": "<record_id>"
}
},
{
"id": "<primary_record_field_id>",
"value": {
"name": "<record_name>"
}
},
{
"id": "<primary_contact_field_id>",
"value": {
"email": "<contact_email>"
}
},
{
"id": "<team_selector_field_id>",
"value": {
"email": "<team_email>"
}
},
{
"id": "<rating_field_id>",
"value": 5
},
{
"id": "<rating_field_id>",
"value": {
"id": "<rating_option_id>"
}
},
{
"name": "email_status",
"value": {
"id": "<option_id>"
}
},
{
"name": "email_status",
"value": {
"name": "Opted In"
}
},
{
"name": "text_field",
"value": "text"
},
{
"name": "dropdown_field",
"value": {
"id": "<option_id>"
}
},
{
"name": "dropdown_field",
"value": {
"name": "<option_name>"
}
},
{
"name": "dropdown_field2",
"value": "<option_id>"
}
],
"archived_conflict": "overwrite"
}{
"object_type": "text",
"num_upcoming_activities": 1,
"fields": {
"id": {
"id": "text",
"field_type": "text",
"display_name": "text",
"value": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"client_info": {
"num_addresses_v2": 1,
"display_name": "text",
"email_on_suppression_list": true
},
"access": {
"view": true,
"edit": true,
"remove": true
},
"num_associated_team_members": 1,
"lead_source_types": [
{
"value": "organic_search",
"label": "text"
}
]
}Partial Update a Record (PATCH)
Want to try the API out? Visit our Swagger docs.
Update entity record (partial)
^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$If true, return all fields even if not updated
Updates the identifier of matching archived record to not raise a conflict.
overwrite- overwrite
overwrite- overwrite
PATCH /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 804
{
"fields": [
{
"id": "<integer_field_id>",
"value": 100
},
{
"id": "<primary_field_id>",
"value": "<record_id>"
},
{
"id": "<primary_field2_id>",
"value": {
"id": "<record_id>"
}
},
{
"id": "<primary_record_field_id>",
"value": {
"name": "<record_name>"
}
},
{
"id": "<primary_contact_field_id>",
"value": {
"email": "<contact_email>"
}
},
{
"id": "<team_selector_field_id>",
"value": {
"email": "<team_email>"
}
},
{
"id": "<rating_field_id>",
"value": 5
},
{
"id": "<rating_field_id>",
"value": {
"id": "<rating_option_id>"
}
},
{
"name": "email_status",
"value": {
"id": "<option_id>"
}
},
{
"name": "email_status",
"value": {
"name": "Opted In"
}
},
{
"name": "text_field",
"value": "text"
},
{
"name": "dropdown_field",
"value": {
"id": "<option_id>"
}
},
{
"name": "dropdown_field",
"value": {
"name": "<option_name>"
}
},
{
"name": "dropdown_field2",
"value": "<option_id>"
}
],
"archived_conflict": "overwrite"
}{
"object_type": "text",
"num_upcoming_activities": 1,
"fields": {
"id": {
"id": "text",
"field_type": "text",
"display_name": "text",
"value": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"client_info": {
"num_addresses_v2": 1,
"display_name": "text",
"email_on_suppression_list": true
},
"access": {
"view": true,
"edit": true,
"remove": true
},
"num_associated_team_members": 1,
"lead_source_types": [
{
"value": "organic_search",
"label": "text"
}
]
}Archive a Record (DELETE)
Want to try the API out? Visit our Swagger docs.
Archive entity record
^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$No response body
No content
DELETE /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Accept: */*
No response body
No content
List Field Values for a Record Field (GET)
Want to try the API out? Visit our Swagger docs.
Useful when retrieving all values from a summarized relationship field
A page number within the paginated result set.
Number of results to return per page.
123http://api.example.org/accounts/?page=4http://api.example.org/accounts/?page=2["error message"]GET /api/records/{entity_id}/field-values/{field_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Accept: */*
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"first_name": "text",
"last_name": "text",
"full_name": "text",
"email": "text",
"display_name": "text"
}
],
"errors": [
"error message"
]
}Manage Records by ID Schemas
Retrieve a Record Schema
Update a Record Schema
Partial Update a Record Schema
List Field Values for a Record Field Schema
What’s Next
After managing your Records by ID, you can:
Retrieve a Record by name or email to resolve identifiers when a Record ID is not yet known
Search Records to select candidate Records before performing ID-based operations
Use the Upsert API to implement conditional create-or-update workflows
Combine ID-based management with lookup or search patterns for synchronization scenarios
Incorporate Record management endpoints into schema-aware integrations
For more information on Record operations, see the related Records API topics below:
Last updated
Was this helpful?