For AI agents: markdown of this page — /docs-content-en/entities/tasks/bind-crm-item.md documentation index — /llms.txt

Bind CRM item to task

POST /v1/tasks/:taskId/bind-crm-item

Binds a CRM item, such as a deal, to a task on behalf of the key's user.

Parameters

Parameter Type Required Description
ParametertaskId (path) Typenumber Requiredyes DescriptionTask ID. List: GET /v1/tasks

Request fields (body)

Field Type Required Description
FieldcrmItemId Typestring Requiredyes DescriptionReference to a specific CRM item: a type prefix and an ID, for example D_123 — the deal with ID 123. Deal IDs: GET /v1/deals

Any field other than crmItemId is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST 'https://vibecode.bitrix24.com/v1/tasks/289/bind-crm-item' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"crmItemId":"D_123"}'

curl — OAuth application

Terminal 
curl -X POST 'https://vibecode.bitrix24.com/v1/tasks/289/bind-crm-item' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"crmItemId":"D_123"}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/bind-crm-item', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"crmItemId":"D_123"}),
})
const result = await response.json()
console.log(result.data.success)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/tasks/289/bind-crm-item', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"crmItemId":"D_123"}),
})
const result = await response.json()
console.log(result.data.success)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionBinding result
Fielddata.success Typeboolean Descriptiontrue — the CRM item is bound to the task

Response example

JSON 
{
  "success": true,
  "data": {
    "success": true
  }
}

Error response example

403 — Bitrix24 refused the binding:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "This action is unavailable.",
    "hint": "Bitrix24 refused this call; the cause is not determined.",
    "cause": "unknown",
    "fix": {
      "action": "none"
    }
  }
}

The error.message text comes from Bitrix24. Branch on error.code, not on the message text.

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId is not a positive integer: taskId must be a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object: body must be an object
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains fields other than crmItemId: body contains unsupported fields
HTTP400 CodeINVALID_PARAMS DescriptioncrmItemId is missing or an empty string: crmItemId must be a non-empty string
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no valid Bitrix24 token
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task or tasks scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused the binding: This action is unavailable.
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the binding for another reason

The full list of common API errors — Errors.

See also