## 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 |
|----------|-----|:-----:|----------|
| `chatId` (path) | number | yes | Open channel chat ID — a positive integer without the `chat` prefix. List: the `chatId` field in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response |

The request body is empty.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|------|-----|----------|
| `success` | boolean | `true` when the dialog's link was read after the call |
| `data.chatId` | number | Chat ID from the request |
| `data.crmEntityType` | string | Type of the CRM card the dialog is linked to: `lead`, `deal`, `company` or `contact` |
| `data.crmEntityId` | number | ID of the CRM card the dialog is linked to |
| `data.leadId` | number \| null | Lead 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 |
|------|-----|----------|
| 400 | `INVALID_JSON_BODY` | A request body was sent and cannot be parsed as JSON. Checked before the path `chatId` is parsed |
| 400 | `INVALID_CHAT_ID` | `chatId` in the path is not a positive integer, including the `chat123` form, or is greater than 9007199254740991. Bitrix24 is not called |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 did not find a chat with that `chatId` |
| 403 | `BITRIX_ACCESS_DENIED` | The employee making the call has no rights to the dialog, so the lead is not created |
| 403 | `BITRIX_ACCESS_DENIED` | Message `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 |
| 422 | `BITRIX_ERROR` | Bitrix24 refused to create the lead; its code is returned in `error.b24Code` |
| 502 | `OPENLINE_OPERATOR_FAILED` | Bitrix24 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 |
| 403 | `SCOPE_DENIED` | The key lacks the `imopenlines` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized |
| 401 | `TOKEN_MISSING` | A personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in `Authorization` |
| 429 | `RATE_LIMITED` | The 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` |
| 429 | `RATE_LIMITED` | Bitrix24 rejected the call under its request rate limit for the portal. The response carries a `Retry-After` header |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or the connection to it dropped before the full response |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond in time. The lead may still have been created |

Full list of common API errors — [Errors](/docs/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

- [Send a message to the client](/docs/openlines/crm/messages)
- [CRM chat members](/docs/openlines/crm/members)
- [Chats by CRM card](/docs/openlines/crm-chats)
- [Search sessions](/docs/openlines/sessions/search)
- [Get a lead](/docs/entities/leads/get)