> 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/add-records-api.md).
# Add Records API
{% hint style="success" %}
**Audience:** Developers, Integration Engineers, Solution Architects
space.vars.entitys within an object using the Add space.vars.entities endpoint and how schema configuration governs space.vars.entity creation.
{% endhint %}
## Overview
Use the **Add Records** endpoint to create new space.vars.entities within a specified space.vars.object via API.
space.vars.entity creation is schema-driven. Submitted values must align with the space.vars.object’s configured structure, including required fields, field types, validation rules, and selectable value constraints. Requests that do not conform to the schema will fail validation.
This page builds on concepts introduced in [Records Core Concepts](/docs/concepts/objects/records/records-core-concepts.md) and the [Object Data Model](/docs/concepts/objects/object-data-model.md).
### Why Use This API
Use the Add space.vars.entities endpoint when you need to create entirely new space.vars.entities programmatically.
Common scenarios include:
* Creating space.vars.entities from external systems (CRM, custom apps)
* Supporting event-driven workflows
* Migrating data into the platform
* Automating operational data capture
* Generating space.vars.entities through backend integrations
* Creating pipeline, standard, or space.vars.object space.vars.entities at scale
This endpoint is appropriate when:
* The space.vars.entity does not already exist
* You intend to create a net-new space.vars.entity
Duplicate prevention is built-in with space.vars.Kizen\_company\_name, as every space.vars.entity must have a unique identifier, which prevents duplicates from being created. If you need to Lookup a space.vars.entity or Create a space.vars.entity or Update a space.vars.entity via Upsert, check out these APIs:
* [Lookup Record API](/docs/concepts/objects/records/records-apis/lookup-record-api.md)**:** Check for existing space.vars.entitys before creation
* [Create or Update Records (Upsert) API](/docs/concepts/objects/records/records-apis/create-or-update-records-upsert-api.md)**:** Create or update in a single request
### Add Records API Behavior
Use this endpoint to create new space.vars.entities within a specified space.vars.object. It:
* Creates a new space.vars.entity based on the space.vars.object’s current schema configuration
* Validates required fields, field types, validation rules, and selectable values at submission
* Rejects unsupported or invalid values and does not create the space.vars.entity if validation fails
* Enforces space.vars.object-, space.vars.entity-, and field-level permissions before allowing creation
* Immediately activates space.vars.automations, reporting, and permission evaluation upon success
* Does not modify existing space.vars.entities
***
## Add Records API Endpoint
Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/records/records_add_create) docs.
## 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":""}}}}}}
```
***
### Add Records Schema
## The EntityRecordAddRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"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]}}}}
```
***
## What’s Next
After creating space.vars.entities, you can use the Search space.vars.entities API to:
* Query space.vars.entities within an space.vars.object using filters, search terms, and pagination
* Retrieve space.vars.entities dynamically for validation, enrichment, or synchronization workflows
* Reference field identifiers when constructing search filters and payloads
* Use space.vars.object and field metadata to build schema-aware queries
* Combine space.vars.entity searches with space.vars.automation triggers, or downstream integrations
For more information, review the related space.vars.entity API topics below:
Related Topics
* [Manage Records by ID API](/docs/concepts/objects/records/records-apis/manage-records-by-id-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)
---
# 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/add-records-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.