Convert

[POST] .../v1/lead/convert

Converts a CRM lead to a deal. Use this workflow method after a lead is qualified and should become a CRM deal instead of being closed as unsuccessful. The method validates target_entity_type, lead status, pipeline access, existing participants, deal inputs and the lead pipeline won stage, creates a deal through Deal/Add semantics with lead client, amount, responsible user, participants, currency and custom fields, marks the lead Converted, links converted_deal_id, moves the lead to the won stage, closes the lead chat, writes stage history and chat system messages, sends LeadStageSet and LeadConverted webhooks and returns the created deal new_id. The request body is required; id must be positive, target_entity_type must be Deal, deal_title is required and limited by the schema, deal_type_id cannot be negative and successful terminal stage movement should use this method rather than Lead/SetStage or Lead/Close. The caller must have CRM lead convert permission or CRM manage-all access for this workflow; missing body, invalid id, invalid target_entity_type, missing deal_title, missing lead, already converted lead, denied pipeline access, missing won stage, downstream Deal/Add validation errors, 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 Deal amount. If omitted, lead.amount is used when it is set on the lead.
currency_id Int64 Optional Currency ID from ctlg_common_currency_ref.crnc_id.
deal_title String Required Title of the deal to create. Maximum length is 300 characters.
deal_type_id Int64 Optional Deal type ID.
fields Array of FieldValueAdd Optional Custom fields for the deal.
id Int64 Required Lead ID.
participant_user_ids Array of Int64 Optional Deal participant user IDs.
pipeline_id Int64 Optional Deal pipeline ID.
responsible_user_id Int64 Optional Responsible user ID for the deal.
stage_id Int64 Optional Deal stage ID.
target_entity_type String Required Target entity type. Only Deal is allowed. Allowed values: Default, Lead, Deal, Client, Ticket.

Request Example

{
  "id": 105,
  "target_entity_type": "Deal",
  "deal_title": "Website wholesale deal",
  "deal_type_id": 3,
  "pipeline_id": 8,
  "stage_id": 33,
  "responsible_user_id": 31,
  "participant_user_ids": [
    18,
    31
  ],
  "amount": 2800.00,
  "currency_id": 1,
  "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
  }
}