---
title: "Add leads"
method: POST
path: "/api/v4/leads"
---

# Add leads

`POST /api/v4/leads`

This method allows adding multiple or singular leads into the account.

## Headers

- `Content-Type` string

## Request body

- object
  - `RAW_BODY` object[]
    - `name` string — Lead name
    - `price` number — Lead sale
    - `status_id` integer — Stage ID the lead is added to. The first stage of the main pipeline by default
    - `pipeline_id` integer — Pipeline ID the lead is added to.
    - `created_by` integer — The ID of the user creating the lead. When passing the value 0, the lead will be considered as created by the robot.
    - `updated_by` integer — The ID of the user updating the lead. When passing the value 0, the lead will be considered as created by the robot.
    - `created_at` integer — Lead creation date in the format of Unix Timestamp.
    - `updated_at` integer — Lead update date 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 of the current lead custom fields’ values.
    - `_embedded` object — Embedded entities of the lead
      - `tags` object[] — Tags attached to the lead.
        - `id` integer — Tag ID
        - `name` string — Tag name
      - `contacts` object[] — Contacts attached to the lead.
        - `id` integer — Contact ID.
        - `is_main` boolean — Indicates whether the contact is the main or not.
      - `companies` object[] — Company attached to the lead. you can assign only 1 company.
        - `id` integer — Company ID.
      - `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` 'widget' — 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
  - `_links` object
    - `self` object
      - `href` string
  - `_embedded` object
    - `leads` object[]
      - `id` integer
      - `request_id` string
      - `_links` object
        - `self` object
          - `href` string

## Other responses

- `400` — 400
- `401` — 401
- `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)