> 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

Use the Add Records API to create new object records via REST with schema validation, required field enforcement, and workflow activation.

{% hint style="success" %}
**Audience:** Developers, Integration Engineers, Solution Architects

How to create <code class="expression">space.vars.entities</code> within an object using the Add <code class="expression">space.vars.entities</code> endpoint, and how schema configuration governs <code class="expression">space.vars.entity</code> creation.
{% endhint %}

## Overview

Use the **Add Records** endpoint to create new <code class="expression">space.vars.entities</code> within a specified <code class="expression">space.vars.object</code> via API.

<code class="expression">space.vars.entity</code> creation is schema-driven. Submitted values must align with the <code class="expression">space.vars.object</code>’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](https://developer.kizen.com/docs/concepts/objects/records/records-core-concepts.md) and the [Object Data Model](https://developer.kizen.com/docs/concepts/objects/object-data-model.md).

### Why Use This API

Use the Add <code class="expression">space.vars.entities</code> endpoint when you need to create entirely new <code class="expression">space.vars.entities</code> programmatically.

Common scenarios include:

* Creating <code class="expression">space.vars.entities</code> from external systems (CRM, custom apps)
* Supporting event-driven workflows
* Migrating data into the platform
* Automating operational data capture
* Generating <code class="expression">space.vars.entities</code> through backend integrations
* Creating pipeline, standard, or <code class="expression">space.vars.object</code> <code class="expression">space.vars.entities</code> at scale

This endpoint is appropriate when:

* The <code class="expression">space.vars.entity</code> does not already exist
* You intend to create a net-new <code class="expression">space.vars.entity</code>

Duplicate prevention is built in with <code class="expression">space.vars.Kizen\_company\_name</code>, as every <code class="expression">space.vars.entity</code> must have a unique identifier, which prevents duplicates from being created. To look up an existing <code class="expression">space.vars.entity</code>, or to create or update a <code class="expression">space.vars.entity</code> in a single request (upsert), use these APIs:

* [Lookup Record API](https://developer.kizen.com/docs/concepts/objects/records/records-apis/lookup-record-api.md)**:** Check for existing <code class="expression">space.vars.entity</code>s before creation
* [Create or Update Records (Upsert) API](https://developer.kizen.com/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 <code class="expression">space.vars.entities</code> within a specified <code class="expression">space.vars.object</code>. It:

* Creates a new <code class="expression">space.vars.entity</code> based on the <code class="expression">space.vars.object</code>’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 <code class="expression">space.vars.entity</code> if validation fails
* Enforces <code class="expression">space.vars.object</code>-, <code class="expression">space.vars.entity</code>-, and field-level permissions before allowing creation
* Immediately activates <code class="expression">space.vars.automations</code>, reporting, and permission evaluation upon success
* Does not modify active <code class="expression">space.vars.entities</code> and can restore archived matches, depending on the unarchive mode

## Unarchiving Using Add Records

When the name of a new <code class="expression">space.vars.entity</code> (or the email for <code class="expression">space.vars.contacts</code>) matches an archived <code class="expression">space.vars.entity</code>, the Add <code class="expression">space.vars.entities</code> endpoint follows the archive conflict mode in the request. Set the `unarchive` field to choose the behavior.

| Mode                   | Archived match found                                                                                                                                                            | Submitted fields                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `prompt`               | Returns a 409 conflict so the caller can choose a mode                                                                                                                          | Not applied                                                               |
| `unarchive`            | Restores the archived <code class="expression">space.vars.entity</code>                                                                                                         | Ignored                                                                   |
| `unarchive_and_update` | Restores the archived <code class="expression">space.vars.entity</code>                                                                                                         | Applied to the restored <code class="expression">space.vars.entity</code> |
| `overwrite`            | Creates a new <code class="expression">space.vars.entity</code>. The archived <code class="expression">space.vars.entity</code> keeps its history under a discarded identifier. | Applied to the new <code class="expression">space.vars.entity</code>      |
| omitted or null        | Restores the archived <code class="expression">space.vars.entity</code>                                                                                                         | Ignored                                                                   |

These behaviors also apply:

* <code class="expression">space.vars.Kizen\_company\_name</code> checks unarchive permissions first. A caller without them receives a 403 for any mode, including `prompt`.
* `unarchive_and_update` returns a 400 if the owner field is submitted as null.
* Matching on email (<code class="expression">space.vars.contacts</code>) and name (other <code class="expression">space.vars.objects</code>) ignores case.

### Example Request

This request creates a <code class="expression">space.vars.contact</code>. If an archived <code class="expression">space.vars.contact</code> has the email `amanda@example.com`, the request restores that <code class="expression">space.vars.contact</code> and applies the other submitted fields.

```http
POST /api/records/client_client/add
Content-Type: application/json

{
  "unarchive": "unarchive_and_update",
  "fields": [
    {"name": "email", "value": "amanda@example.com"},
    {"name": "first_name", "value": "Amanda"},
    {"name": "lead_source", "value": "Webinar"}
  ]
}
```

The call returns a `201` status with the ID of the restored <code class="expression">space.vars.entity</code>. If no archived <code class="expression">space.vars.entity</code> matches, the call creates a new <code class="expression">space.vars.contact</code> as usual.

### Concurrency and Endpoint Support

If another request restores or renames the archived <code class="expression">space.vars.entity</code> first, the call returns a 409 with the message `The archived record was changed in another transaction.` The call does not write over the other change.

The legacy client, custom object, and pipeline endpoints do not accept `unarchive_and_update`.

***

## Add Records API Endpoint

Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/published/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"},"userId":{"type":"apiKey","in":"header","name":"X-USER-ID"},"apiKey":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"EntityRecordAddRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"unarchive":{"allOf":[{"$ref":"#/components/schemas/RecordUnarchiveEnum"}],"nullable":true,"description":"Behavior when a matching archived record exists: 'prompt' returns a conflict, 'unarchive' restores it without applying the submitted fields, 'unarchive_and_update' restores it and applies the submitted fields, 'overwrite' creates a new record. When omitted, the archived record is restored without applying the submitted fields.\n\n* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite\n* `unarchive_and_update` - unarchive_and_update"}},"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":{"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."}}},"RecordUnarchiveEnum":{"enum":["prompt","unarchive","overwrite","unarchive_and_update"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite\n* `unarchive_and_update` - unarchive_and_update"},"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

Send an `EntityRecordAddRequest` object as the request body. It has two properties:

* `fields` (required): One entry per field you set on the new <code class="expression">space.vars.entity</code>. Identify each field by `id` or `name`, then give its `value`, or `add_values` for fields that allow multiple values.
* `unarchive` (optional): What to do when the new <code class="expression">space.vars.entity</code> matches an archived <code class="expression">space.vars.entity</code>. See [Unarchiving Using Add Records](#unarchiving-using-add-records).

Expand the panel below to see every property.

## 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":{"allOf":[{"$ref":"#/components/schemas/RecordUnarchiveEnum"}],"nullable":true,"description":"Behavior when a matching archived record exists: 'prompt' returns a conflict, 'unarchive' restores it without applying the submitted fields, 'unarchive_and_update' restores it and applies the submitted fields, 'overwrite' creates a new record. When omitted, the archived record is restored without applying the submitted fields.\n\n* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite\n* `unarchive_and_update` - unarchive_and_update"}},"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":{"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."}}},"RecordUnarchiveEnum":{"enum":["prompt","unarchive","overwrite","unarchive_and_update"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite\n* `unarchive_and_update` - unarchive_and_update"}}}}
```

***

## What’s Next

After creating <code class="expression">space.vars.entities</code>, you can use the Search <code class="expression">space.vars.entities</code> API to:

* Query <code class="expression">space.vars.entities</code> within an <code class="expression">space.vars.object</code> using filters, search terms, and pagination
* Retrieve <code class="expression">space.vars.entities</code> dynamically for validation, enrichment, or synchronization workflows
* Reference field identifiers when constructing search filters and payloads
* Use <code class="expression">space.vars.object</code> and field metadata to build schema-aware queries
* Combine <code class="expression">space.vars.entity</code> searches with <code class="expression">space.vars.automation</code> triggers, or downstream integrations

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

<details>

<summary>Related Topics</summary>

* [Manage Records by ID API](https://developer.kizen.com/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md)
* [Lookup Record API](https://developer.kizen.com/docs/concepts/objects/records/records-apis/lookup-record-api.md)
* [Search Records API](https://developer.kizen.com/docs/concepts/objects/records/records-apis/search-records-api.md)
* [Create or Update Records (Upsert) API](https://developer.kizen.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/concepts/objects/records/records-apis/add-records-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
