For AI agents: markdown of this page — /docs-content-en/openlines/crm/lead.md documentation index — /llms.txt

Create a lead from an inquiry

POST /v1/openlines/dialogs/:chatId/lead

Creates a CRM lead from an open channel dialog and returns the CRM card the dialog is linked to after the call. If a CRM card is already linked to the dialog, no new lead is created and the existing link is returned.

Parameters

Parameter Type Required Description
ParameterchatId (path) Typenumber Requiredyes DescriptionOpen channel chat ID — a positive integer without the chat prefix. List: the chatId field in the POST /v1/openlines/sessions/search response

The request body is empty.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
if (data.leadId === null) {
  console.log(`Dialog already linked: ${data.crmEntityType} ${data.crmEntityId}`)
} else {
  console.log('Lead:', data.leadId)
}

JavaScript — OAuth application

javascript 
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the dialog's link was read after the call
Fielddata.chatId Typenumber DescriptionChat ID from the request
Fielddata.crmEntityType Typestring DescriptionType of the CRM card the dialog is linked to: lead, deal, company or contact
Fielddata.crmEntityId Typenumber DescriptionID of the CRM card the dialog is linked to
Fielddata.leadId Typenumber | null DescriptionLead ID when the dialog is linked to a lead. null when the dialog is linked to a deal, company or contact

Response example

The dialog is linked to a lead:

JSON 
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "lead",
    "crmEntityId": 42,
    "leadId": 42
  }
}

A deal was already linked to the dialog:

JSON 
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "deal",
    "crmEntityId": 42,
    "leadId": null
  }
}

Error response example

400 — chatId in the path is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_CHAT_ID",
    "message": "chatId must be a positive safe integer"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_JSON_BODY DescriptionA request body was sent and cannot be parsed as JSON. Checked before the path chatId is parsed
HTTP400 CodeINVALID_CHAT_ID DescriptionchatId in the path is not a positive integer, including the chat123 form, or is greater than 9007199254740991. Bitrix24 is not called
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 did not find a chat with that chatId
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe employee making the call has no rights to the dialog, so the lead is not created
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionMessage Bitrix24 refused the dialog: it is absent or inaccessible: Bitrix24 accepted the call but denied reading the dialog's link. The lead may still have been created
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused to create the lead; its code is returned in error.b24Code
HTTP502 CodeOPENLINE_OPERATOR_FAILED DescriptionBitrix24 did not confirm the lead creation, or the dialog's CRM link could not be read after the call. The lead may still have been created
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imopenlines scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_MISSING DescriptionA personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in Authorization
HTTP429 CodeRATE_LIMITED DescriptionThe limit of 120 requests per minute per portal was exceeded. The limit is divided across platform replicas, so the code can arrive before the 120th request. The effective value for the key is in the x-ratelimit-limit header, the remaining quota is in x-ratelimit-remaining
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 rejected the call under its request rate limit for the portal. The response carries a Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or the connection to it dropped before the full response
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond in time. The lead may still have been created

Full list of common API errors — Errors.

Known specifics

  • Retrying after a failure is safe. After 502 OPENLINE_OPERATOR_FAILED, 503 BITRIX_TIMEOUT and 403 BITRIX_ACCESS_DENIED the call can be repeated: if the first call managed to create the lead, the repeated one does not create a second lead and returns the existing link.

See also