# Records

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

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

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

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

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

## POST /api/records/{object\_identifier}/add

> Create 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":{"EntityRecordAddRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"unarchive":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/UnarchiveEnum"},{"$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."}}},"UnarchiveEnum":{"enum":["prompt","unarchive","overwrite"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `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}/add":{"post":{"operationId":"records_add_create","description":"Create entity record","parameters":[{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true}],"tags":["records"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordAddRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordDetail"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":""}}}}}}
```

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

## POST /api/records/{object\_identifier}/search

> Search entity records.

```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":{"EntityRecordSearchPayloadRequest":{"type":"object","properties":{"field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to return. Only one of 'field_names' or 'field_ids' is allowed."},"field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed."},"search_within_field_names":{"type":"array","items":{"type":"string","minLength":1},"nullable":true,"description":"List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed."},"search_within_field_ids":{"type":"array","items":{"type":"string","format":"uuid"},"nullable":true,"description":"List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed."},"query":{"type":"array","items":{"$ref":"#/components/schemas/FilterQueryRequest"}},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}},"FilterQueryRequest":{"type":"object","properties":{"filters":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"List of filters to apply."},"and":{"type":"boolean","nullable":true,"default":true,"description":"Whether to apply AND or OR logic in filters"}}},"PaginatedEntityRecordListList":{"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/EntityRecordList"}},"errors":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}]}}},"EntityRecordList":{"type":"object","properties":{"object_type":{"type":"string"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","client_info","fields","id","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"]}}},"paths":{"/api/records/{object_identifier}/search":{"post":{"operationId":"records_search_create","description":"Search entity records.","parameters":[{"in":"query","name":"group_id","schema":{"type":"string"},"description":"Group id to filter records by."},{"in":"query","name":"in_group_ids","schema":{"type":"string"},"description":"Comma separated list of group ids. Only records in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered."},{"in":"query","name":"not_in_group_ids","schema":{"type":"string"},"description":"Comma separated list of group ids. Only records not in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered."},{"in":"path","name":"object_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"ordering","schema":{"type":"string"},"description":"Which field to use when ordering the results."},{"in":"query","name":"page","schema":{"type":"integer"},"description":"A page number within the paginated result set."},{"in":"query","name":"page_size","schema":{"type":"integer"},"description":"Number of results to return per page."},{"in":"query","name":"search","schema":{"type":"string"},"description":"\n                A search term, by default, searches Contact's email, first_name, last_name, home_phone, mobile_phone, business_phone and Record's name. 'search_within_field_names' or 'search_within_field_ids' can be used to specify fields to search within.\n                "}],"tags":["records"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityRecordSearchPayloadRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEntityRecordListList"}}},"description":""}}}}}}
```

## POST /api/records/{object\_identifier}/upsert

> Create or update entity record based on lookup criteria

```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":{"EntityRecordUpsertRequest":{"type":"object","properties":{"lookup_value":{"type":"string","minLength":1,"description":"Value to match the entity record (name for custom objects, email for contacts)."},"oncreate_unarchive":{"nullable":true,"description":"Behavior when creating and a matching archived record exists.\n\n* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/OncreateUnarchiveEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"onupdate_archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict during update.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/OnupdateArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["lookup_value"]},"OncreateUnarchiveEnum":{"enum":["prompt","unarchive","overwrite"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite"},"NullEnum":{"enum":[null]},"OnupdateArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"UpsertRecordResponse":{"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"}},"action":{"$ref":"#/components/schemas/ActionEnum"}},"required":["access","action","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"},"ActionEnum":{"enum":["created","updated","unarchived"],"type":"string","description":"* `created` - created\n* `updated` - updated\n* `unarchived` - unarchived"},"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}/upsert":{"post":{"operationId":"records_upsert_create","description":"Create or update entity record based on lookup criteria","parameters":[{"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/EntityRecordUpsertRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertRecordResponse"}}},"description":""},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertRecordResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":""}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://developer.kizen.com/api/records.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.