Add

[POST] .../v1/lead/add

Creates a CRM lead. Use this method to create a CRM lead from a ticket, chat, website form, manual operator action or integration before it is qualified, closed or converted to a deal. The method validates optional client, ticket, responsible user, pipeline, non-terminal stage, mentions and custom fields, then stores the lead, participants, field values, stage history, linked chat, action log, notifications and LeadAdded/ChatAdded webhooks before returning new_id. The request body is required; pipeline_id defaults to the default Lead pipeline, stage_id defaults to the new/start stage, title is optional but limited by the schema and mentioned users must already be in the lead context unless mention_options.add_missing_users_to_context is true. The caller must have CRM lead add permission and pipeline access; missing body, denied access, missing client or ticket, missing pipeline or stage, terminal stage usage, disabled additional fields, required custom-field failures, mention validation failures, database errors, transaction failures and action-log errors are returned as HTTP 200 ErrorResult business errors.

Request Parameters

Name Type Required Description
amount Decimal Optional Lead amount.
chat_id String Optional UUID of an existing chat to link to the lead. Maximum length is 36 characters.
client_id Int64 Optional CRM client ID.
description String Optional Lead description.
description_mentions Array of CommonMentionInput Optional Structured user mentions in description.
fields Array of FieldValueAdd Optional Custom field values.
mention_options CommonMentionOptions Optional Mention processing options.
participant_user_ids Array of Int64 Optional Lead participant user IDs.
pipeline_id Int64 Optional Pipeline ID. If omitted, the default lead pipeline is used.
responsible_user_id Int64 Optional Responsible user ID.
stage_id Int64 Optional Non-terminal stage ID. If omitted, the pipeline start stage is used.
ticket_id Int64 Optional Source ticket ID used as an informational reference.
title String Optional Lead title. Maximum length is 300 characters.

Request Example

{
  "client_id": 501,
  "ticket_id": 9001,
  "pipeline_id": 7,
  "stage_id": 25,
  "responsible_user_id": 15,
  "participant_user_ids": [
    18
  ],
  "title": "Website request",
  "description": "Client asks for a call after 15:00",
  "amount": 2500.00,
  "fields": []
}

Response Parameters

Name Type Description
ok Boolean Indicates whether the request completed successfully.
result Insert Created record result.

Response Example

{
  "ok": true,
  "result": {
    "new_id": 105
  }
}