Add

[POST] .../v1/deal/add

Creates a CRM deal. Use this method to create a sales deal manually, from a lead, from a ticket, from another deal or with a linked project task before moving it through the deal pipeline. The method validates required title, amount and currency_id, validates optional client, task, source lead, deal type, responsible user, non-terminal stage, pipeline access, custom fields, mentions and preferred chat id, then stores the deal, participants, custom field values, task links, stage history, linked chat, action log, notifications and DealAdded/ChatAdded webhooks before returning new_id. The request body is required; pipeline_id defaults to the default Deal pipeline, stage_id defaults to that pipeline start stage, title is limited by the schema, task_id must be accessible and not linked to another active deal and chat_id cannot point to a task chat. The caller must have CRM deal add permission and pipeline access; missing body, missing required fields, denied access, missing currency/client/lead/task/deal type/stage, terminal stage usage, duplicate active source-lead or task links, 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 Required Deal amount.
chat_id String Optional UUID of an existing chat to link to the deal. Task chats cannot be used. Maximum length is 36 characters.
client_id Int64 Optional CRM client ID.
currency_id Int64 Required Currency ID from ctlg_common_currency_ref.crnc_id.
deal_type_id Int64 Optional Deal type ID.
description String Optional Deal description.
description_mentions Array of CommonMentionInput Optional Structured user mentions in description.
fields Array of FieldValueAdd Optional Custom field values.
lead_id Int64 Optional Source lead ID.
mention_options CommonMentionOptions Optional Mention processing options.
participant_user_ids Array of Int64 Optional Deal participant user IDs.
pipeline_id Int64 Optional Pipeline ID. If omitted, the default deal pipeline is used.
responsible_user_id Int64 Optional Responsible user.
source_deal_id Int64 Optional Source deal ID used as an informational reference.
source_lead_id Int64 Optional Source lead ID used as an informational reference.
stage_id Int64 Optional Non-terminal stage ID. If omitted, the pipeline start stage is used.
task_id Int64 Optional Linked project task ID.
ticket_id Int64 Optional Source ticket ID used as an informational reference.
title String Required Deal title. Maximum length is 300 characters.

Request Example

{
  "client_id": 501,
  "lead_id": 105,
  "deal_type_id": 3,
  "pipeline_id": 8,
  "stage_id": 33,
  "title": "Website wholesale deal",
  "description": "Potential wholesale order after website request",
  "amount": 2800.00,
  "currency_id": 1,
  "responsible_user_id": 31,
  "participant_user_ids": [
    18
  ],
  "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": 230
  }
}