---
title: "Complex addition of leads with contact and company"
method: POST
path: "/api/v4/leads/complex"
---

# Complex addition of leads with contact and company

`POST /api/v4/leads/complex`

The method allows you to add leads with contacts and a company to your account in batches. The added data can be checked in the duplicate control.

## Headers

- `Content-Type` string

## Request body

- object
  - `RAW_BODY` object[]
    - `name` string — Lead name
    - `price` number — Lead sale
    - `status_id` integer — ID of the stage the lead is added to, the first stage of the main pipeline by default
    - `pipeline_id` integer — ID of the pipeline the lead is added to
    - `created_by` integer — Id of the user who created the lead
    - `updated_by` integer — Id of the user who updated the lead
    - `created_at` integer — The time and date the lead was created in the format of Unix Timestamp
    - `updated_at` integer — The time and date the lead was updated in the format of Unix Timestamp
    - `closed_at` integer — Lead closure date in the format of Unix Timestamp
    - `loss_reason_id` integer — Lead loss reason ID
    - `responsible_user_id` integer — Lead responsible user ID
    - `custom_fields_values` string, json — An array containing information about additional fields specified for the added lead. The field is optional. You can transfer no more than 40 fields for one lead. If you need to pass more, you can perform an update operation after creation or create through a common method that does not check for duplicates.
    - `_embedded` object — Embedded entities data
      - `tags` object[]
        - `id` integer — Tag ID
        - `name` string — Tag name
      - `contacts` object[] — Linked contacts data array. This array always consists of 1 element as the method accepts only one contact.
        - `id` string — Contact ID
        - `name` string — Contact full name
        - `first_name` string — Contact first name
        - `last_name` string — Contact last name
        - `responsible_user_id` integer — Contact responsible user ID
        - `created_by` integer — ID of the user who created the contact
        - `updated_by` integer — ID of the user who updated the contact last
        - `created_at` integer — Contact creation date in the format of Unix Timestamp
        - `updated_at` integer — Contact update date in the format of Unix Timestamp
        - `custom_fields_values` string, json — An array of the current contact custom fields’ values
        - `tags_to_add` object[] — Array of tags to add. You need to pass either name or ID of the tag.
          - `id` integer — Tag ID
          - `name` string — Tag name
        - `request_id` string — The field will be returned unchanged in the response and will not be saved.
      - `companies` object[] — Linked company data array. This array always consists of 1 element, as a lead can have only one company linked to it.
        - `name` string
        - `custom_fields_values` object[]
          - `type` 'text' | 'numeric' | 'checkbox' | 'select' | 'multiselect' | 'date' | 'url' | 'textarea' | 'radiobutton' | 'streetaddress' | 'smart_address' | 'birthday' | 'legal_entity' | 'date_time' | 'price' | 'category' | 'file', required — Field type
          - `name` string, required — Field name
          - `code` string — Field code that can be used to update the value of the field without passing the field ID in the request
          - `sort` integer — Field sorting in the field group
          - `group_id` string — Field group ID
          - `is_api_only` boolean — Defines whether the field is editable via API only
          - `required_statuses` object[] — Array of the fields required to change a lead status
            - `status_id` integer — ID of the stage which requires the current field to have a value before the lead can be moved
            - `pipeline_id` integer — ID of the pipeline which requires the current field to have a value before the lead can be moved
          - `remind` string — Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event)
          - `enums` object[] — Mandatory for the following field types: multiselect/radiobutton/select
            - `value` string — Value
            - `sort` integer — Value sorting
            - `code` string — Value symbolic code
          - `nested` object[] — Available for the following field types: category
            - `id` integer — Nested value ID. Shouldn’t be passed when creating a new value
            - `parent_id` integer — Nested value parent ID
            - `value` string — The value of the nested value
            - `sort` integer — Nested value sorting
            - `request_id` string — Temporary identifier of a nested value. Identifier should be unique for the request, isn’t saved anywhere, and is used to create more than one nesting level within one request
            - `parent_request_id` string — Temporary identifier of a nested value parent. Identifier is used only at the time of the request, isn’t saved anywhere, and defines the nesting level of the added element if the parent element hasn’t been created yet
        - `responsible_user_id` integer — Company responsible user ID
      - `metadata` string, json — An object containing the metadata for the entity being created in the incoming lead. If metadata is passed, we consider it to be an incoming lead, and any status passed other than the incoming lead will be ignored. The parameters are the same as those passed when creating an incoming lead, except for the need to pass an additional category key. Additionally, you need to pass "category" (sip or forms) in the object. Read more about metadata parameters: https://developers.kommo.com/reference/metadata
      - `source` object — Source of the lead
        - `external_id` string — The external ID of the source. A source can be added using the Sources API. If the external_id of the source is passed and the pipeline_id is not passed, the lead will be added to the pipeline where the source is located.
        - `type` string — Source type. For leads added by integrations, only the widget is supported.
    - `tags_to_add` object[] — Array of tags to add. You need to pass either name or ID of the tag.
      - `id` integer — Tag ID
      - `name` string — Tag name

## Response `200`

200

- object[]
  - `id` integer
  - `contact_id` integer
  - `company_id` integer
  - `request_id` string[]
  - `merged` boolean

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/kommo/apis/kommo-api-references.md) · [All operations](https://skmtc.net/kommo/apis/kommo-api-references/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kommo/kommo-api-references/versions/f17af4d23c7c/schema)