> 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/manage-records-by-id-api.md).

# Manage Records by ID API

{% hint style="success" %}
**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.
{% endhint %}

## Overview

Use the **Manage Records by ID** endpoints to retrieve, update, partially update, and archive existing <code class="expression">space.vars.entities</code> using their system-generated record IDs. You can use them to operate on a specific <code class="expression">space.vars.entity</code>’s current state, apply full or targeted changes, and manage lifecycle actions while preserving audit history.

These endpoints are designed for precise, ID-based <code class="expression">space.vars.entity</code> management. They enable external systems to synchronize <code class="expression">space.vars.entity</code> 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 <code class="expression">space.vars.entity</code> name or email.

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 Managing <code class="expression">space.vars.entities</code> by ID endpoints when you need to:

* Synchronize <code class="expression">space.vars.entity</code> updates from an external system into <code class="expression">space.vars.Kizen\_company\_name</code>
* Retrieve the current state of a <code class="expression">space.vars.entity</code> before applying changes
* Update <code class="expression">space.vars.entity</code> field values in response to lifecycle events
* Apply targeted updates without sending a full <code class="expression">space.vars.entity</code> payload
* Archive <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.entity</code> control and are recommended once the <code class="expression">space.vars.entity</code> ID is known.

### Manage Records by ID API Behavior

Use these endpoints to retrieve, modify, and manage <code class="expression">space.vars.entities</code> using a system-generated <code class="expression">space.vars.entity</code> ID. They:

* **GET** retrieves a <code class="expression">space.vars.entity</code> and returns its current field values; use when evaluating the current <code class="expression">space.vars.entity</code> state before applying changes
* **PUT** updates a <code class="expression">space.vars.entity</code> using a full update pattern; use when replacing the complete <code class="expression">space.vars.entity</code> payload
* **PATCH** updates specific fields without replacing the full <code class="expression">space.vars.entity</code> payload; use for targeted changes
* **DELETE** archives a <code class="expression">space.vars.entity</code> 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 <code class="expression">space.vars.entity</code> detail response

All operations respect validation rules, permission constraints, and <code class="expression">space.vars.object</code>-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](https://app.go.kizen.com/api/docs/public/swagger#/records/records_retrieve) docs.

## GET /api/records/{object\_identifier}/{entity\_id}

> Get entity record by ID

```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}/{entity_id}":{"get":{"operationId":"records_retrieve","description":"Get entity record by ID","parameters":[{"in":"query","name":"detail_summary","schema":{"type":"boolean"},"description":"Include summary data in the response, including lead sources."},{"in":"path","name":"entity_id","schema":{"type":"string","pattern":"^[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}$"},"required":true},{"in":"query","name":"field_category","schema":{"type":"string"},"description":"Comma separated category ids, to filter by field category.  Ignored when field_ids is present."},{"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":"include_hidden_fields","schema":{"type":"boolean"},"description":"Include hidden fields in the response."},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true}],"tags":["records"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordDetail"}}},"description":""}}}}}}
```

### Update a Record (PUT)

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/records/records_update) docs.

## PUT /api/records/{object\_identifier}/{entity\_id}

> Update entity record

```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":{"EntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["fields"]},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]},"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"},"ErrorResponse":{"type":"object","properties":{"non_field_errors":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/_FieldError"}}},"required":["fields"]},"_FieldError":{"type":"object","description":"This is only used for rendering the error response schema.","properties":{"id":{"type":"array","items":{"type":"string"}},"name":{"type":"array","items":{"type":"string"}},"value":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"description":"Given the *incoming* primitive data, return the value for this field\nthat should be validated and transformed to a native value.","readOnly":true},"add_values":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"readOnly":true},"remove_values":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"readOnly":true}},"required":["add_values","remove_values","value"]}}},"paths":{"/api/records/{object_identifier}/{entity_id}":{"put":{"operationId":"records_update","description":"Update entity record","parameters":[{"in":"path","name":"entity_id","schema":{"type":"string","pattern":"^[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}$"},"required":true},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true}],"tags":["records"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordUpdateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordDetail"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":""}}}}}}
```

### Partial Update a Record (PATCH)

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/records/records_partial_update) docs.

## PATCH /api/records/{object\_identifier}/{entity\_id}

> Update entity record (partial)

```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":{"PatchedEntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}}},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]},"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"},"ErrorResponse":{"type":"object","properties":{"non_field_errors":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/_FieldError"}}},"required":["fields"]},"_FieldError":{"type":"object","description":"This is only used for rendering the error response schema.","properties":{"id":{"type":"array","items":{"type":"string"}},"name":{"type":"array","items":{"type":"string"}},"value":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"description":"Given the *incoming* primitive data, return the value for this field\nthat should be validated and transformed to a native value.","readOnly":true},"add_values":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"readOnly":true},"remove_values":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}],"readOnly":true}},"required":["add_values","remove_values","value"]}}},"paths":{"/api/records/{object_identifier}/{entity_id}":{"patch":{"operationId":"records_partial_update","description":"Update entity record (partial)","parameters":[{"in":"path","name":"entity_id","schema":{"type":"string","pattern":"^[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}$"},"required":true},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"return_all_fields","schema":{"type":"boolean"},"description":"If true, return all fields even if not updated"}],"tags":["records"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedEntityRecordUpdateRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordDetail"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":""}}}}}}
```

### Archive a Record (DELETE)

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/records/records_destroy) docs.

## DELETE /api/records/{object\_identifier}/{entity\_id}

> Archive entity record

```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"}}},"paths":{"/api/records/{object_identifier}/{entity_id}":{"delete":{"operationId":"records_destroy","description":"Archive entity record","parameters":[{"in":"path","name":"entity_id","schema":{"type":"string","pattern":"^[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}$"},"required":true},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true}],"tags":["records"],"responses":{"204":{"description":"No response body"}}}}}}
```

### List Field Values for a Record Field (GET)

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/records/records_field_values_list) docs.

## List values for record field

> Useful when retrieving all values from a summarized relationship field

```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":{"PaginatedFieldValuesList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/FieldValues"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"FieldValues":{"oneOf":[{"$ref":"#/components/schemas/ClientTypeaheadSearch"},{"$ref":"#/components/schemas/RelationshipFieldValue"}]},"ClientTypeaheadSearch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"}},"required":["display_name","email","first_name","full_name","id","last_name"]},"RelationshipFieldValue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"display_name":{"type":"string"}},"required":["display_name","id","name"]}}},"paths":{"/api/records/{entity_id}/field-values/{field_id}":{"get":{"operationId":"records_field_values_list","description":"Useful when retrieving all values from a summarized relationship field","summary":"List values for record field","parameters":[{"in":"path","name":"entity_id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"field_id","schema":{"type":"string","format":"uuid"},"required":true},{"name":"page","required":false,"in":"query","description":"A page number within the paginated result set.","schema":{"type":"integer"}},{"name":"page_size","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"in":"query","name":"search","schema":{"type":"string"}}],"tags":["records"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFieldValuesList"}}},"description":""}}}}}}
```

***

## Manage Records by ID Schemas

### Retrieve a 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"}}}}
```

### Update a 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"}}}}
```

## The EntityRecordUpdateRequest object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["fields"]},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]}}}}
```

### Partial Update a Record Schema

## The PatchedEntityRecordUpdateRequest object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PatchedEntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}}},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]}}}}
```

## 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"}}}}
```

### List Field Values for a Record Field Schema

## The PaginatedFieldValuesList object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PaginatedFieldValuesList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/FieldValues"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"FieldValues":{"oneOf":[{"$ref":"#/components/schemas/ClientTypeaheadSearch"},{"$ref":"#/components/schemas/RelationshipFieldValue"}]},"ClientTypeaheadSearch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string"}},"required":["display_name","email","first_name","full_name","id","last_name"]},"RelationshipFieldValue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"display_name":{"type":"string"}},"required":["display_name","id","name"]}}}}
```

***

## What’s Next

After managing your <code class="expression">space.vars.entities</code> by ID, you can:

* Retrieve a <code class="expression">space.vars.entity</code> by name or email to resolve identifiers when a <code class="expression">space.vars.entity</code> ID is not yet known
* Search <code class="expression">space.vars.entities</code> to select candidate <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.entity</code> management endpoints into schema-aware integrations

For more information on <code class="expression">space.vars.entity</code> operations, see the related <code class="expression">space.vars.entities</code> API topics below:

<details>

<summary>Related Topics</summary>

* [Add Records API](/docs/concepts/objects/records/records-apis/add-records-api.md)
* [Lookup Record API](/docs/concepts/objects/records/records-apis/lookup-record-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)

</details>


---

# 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/manage-records-by-id-api.md?ask=<question>&goal=<endgoal>
```

`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.