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

Get entity record by ID

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

entity_idstringRequiredPattern: ^[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}$

object_identifierstringRequired

Query parameters

detail_summarybooleanOptional

Include summary data in the response, including lead sources.

field_categorystringOptional

Comma separated category ids, to filter by field category. Ignored when field_ids is present.

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.

include_hidden_fieldsbooleanOptional

Include hidden fields in the response.

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

get

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

GET /api/records/{object_identifier}/{entity_id} 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"
    }
  ]
}

Update a Record (PUT)

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

put

Update entity record

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

entity_idstringRequiredPattern: ^[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}$

object_identifierstringRequired

Body

application/json

archived_conflictone of · nullableOptional

Updates the identifier of matching archived record to not raise a conflict.

• overwrite - overwrite

string · enumOptional

• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

400Error

application/json

put

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

PUT /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
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"
}

Single value fieldsMulti value fields

{
  "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.

patch

Update entity record (partial)

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

entity_idstringRequiredPattern: ^[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}$

object_identifierstringRequired

Query parameters

return_all_fieldsbooleanOptional

If true, return all fields even if not updated

Body

application/json

archived_conflictone of · nullableOptional

Updates the identifier of matching archived record to not raise a conflict.

• overwrite - overwrite

string · enumOptional

• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

400Error

application/json

patch

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

PATCH /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
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"
}

Single value fieldsMulti value fields

{
  "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.

delete

Archive entity record

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

entity_idstringRequiredPattern: ^[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}$

object_identifierstringRequired

Responses

204

No response body

delete

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

DELETE /api/records/{object_identifier}/{entity_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Accept: */*

204

No response body

No content

List Field Values for a Record Field (GET)

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

List values for record field

get

Useful when retrieving all values from a summarized relationship field

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

entity_idstring · uuidRequired

field_idstring · uuidRequired

Query parameters

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=4

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?page=2

errorsone ofOptionalExample: ["error message"]

nullOptional

or

string[]Optional

get

/api/records/{entity_id}/field-values/{field_id}

HTTPcURLJavaScriptPython

GET /api/records/{entity_id}/field-values/{field_id} HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Accept: */*

200Success

{
  "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:

Related Topics

• Add Records API

• Lookup Record API

• Search Records API

• Create or Update Records (Upsert) API