Add Records API

Audience: Developers, Integration Engineers, Solution Architects

Records within an object using the Add Records endpoint and how schema configuration governs Record creation.

Overview

Use the Add Records endpoint to create new Records within a specified Object via API.

Record creation is schema-driven. Submitted values must align with the 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 and the Object Data Model.

Why Use This API

Use the Add Records endpoint when you need to create entirely new Records programmatically.

Common scenarios include:

• Creating Records from external systems (CRM, custom apps)

• Supporting event-driven workflows

• Migrating data into the platform

• Automating operational data capture

• Generating Records through backend integrations

• Creating pipeline, standard, or Object Records at scale

This endpoint is appropriate when:

• The Record does not already exist

• You intend to create a net-new Record

Duplicate prevention is built-in with Kizen, as every Record must have a unique identifier, which prevents duplicates from being created. If you need to Lookup a Record or Create a Record or Update a Record via Upsert, check out these APIs:

• Lookup Record API: Check for existing Records before creation

• Create or Update Records (Upsert) API: Create or update in a single request

Add Records API Behavior

Use this endpoint to create new Records within a specified Object. It:

• Creates a new Record based on the 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 Record if validation fails

• Enforces Object-, Record-, and field-level permissions before allowing creation

• Immediately activates workflows, automation, reporting, and permission evaluation upon success

• Does not modify existing Records

---

Add Records API Endpoint

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

post

Create entity record

Authorizations

apiKey & businessId & userId

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

object_identifierstringRequired

Body

application/json

unarchiveone of · nullableOptional

string · enumOptional

• prompt - prompt
• unarchive - unarchive
• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

object_typestringRequired

num_upcoming_activitiesintegerRequired

idstring · uuidRequired

num_associated_team_membersintegerRequired

400Error

application/json

post

/api/records/{object_identifier}/add

HTTPcURLJavaScriptPython

POST /api/records/{object_identifier}/add HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 793

{
  "fields": [
    {
      "id": "<integer_field_id>",
      "value": 100
    },
    {
      "id": "<primary_field_id>",
      "value": "<record_id>"
    },
    {
      "id": "<primary_field2_id>",
      "value": {
        "id": "<record_id>"
      }
    },
    {
      "id": "<primary_record_field_id>",
      "value": {
        "name": "<record_name>"
      }
    },
    {
      "id": "<primary_contact_field_id>",
      "value": {
        "email": "<contact_email>"
      }
    },
    {
      "id": "<team_selector_field_id>",
      "value": {
        "email": "<team_email>"
      }
    },
    {
      "id": "<rating_field_id>",
      "value": 5
    },
    {
      "id": "<rating_field_id>",
      "value": {
        "id": "<rating_option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "name": "Opted In"
      }
    },
    {
      "name": "text_field",
      "value": "text"
    },
    {
      "name": "dropdown_field",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "dropdown_field",
      "value": {
        "name": "<option_name>"
      }
    },
    {
      "name": "dropdown_field2",
      "value": "<option_id>"
    }
  ],
  "unarchive": "prompt"
}

Single value fieldsMulti value fields

{
  "id": "<entity_record_id>",
  "fields": {
    "<email_field_id>": {
      "name": "email",
      "value": "[email protected]"
    },
    "<first_name_field_id>": {
      "name": "first_name_field_name",
      "value": "first name"
    },
    "<last_name_field_id>": {
      "name": "last_name_field_name",
      "value": "last name"
    },
    "<created_field_id>": {
      "name": "created",
      "value": "2020-01-30 01:00:00"
    },
    "<updated_field_id>": {
      "name": "updated",
      "value": "2020-01-30 01:00:00"
    }
  }
}

---

Add Records Schema

---

What’s Next

After creating Records, you can use the Search Records API to:

• Query Records within an Object using filters, search terms, and pagination

• Retrieve Records dynamically for validation, enrichment, or synchronization workflows

• Reference field identifiers when constructing search filters and payloads

• Use Object and field metadata to build schema-aware queries

• Combine Record searches with automation, workflow triggers, or downstream integrations

For more information, review the related Record API topics below:

Related Topics

• Manage Records by ID API

• Lookup Record API

• Search Records API

• Create or Update Records (Upsert) API