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

Finish a call

POST /v1/calls/:callId/finish

Finishes a registered call: records the duration and the final status, and creates an activity in the linked CRM entity. Call it after the conversation ends, before attaching a transcription.

Parameters

Parameter In Type Required Description
ParametercallId Inpath Typestring Requiredyes DescriptioncallId from the POST /v1/calls/register response

Request fields (body)

Parameter Type Required Default Description
ParameteruserId Typenumber Requiredyes Default— DescriptionID of the Bitrix24 user who finished the call. A positive integer. A numeric string such as "42" is also accepted. Employees
Parameterduration Typenumber Requiredyes Default— DescriptionCall duration in seconds. A non-negative number. A numeric string is also accepted
ParameterstatusCode Typestring Requiredno Default"200" when duration > 0, otherwise "304" DescriptionCompletion code: "200" success, "304" missed, "403" forbidden, "486" busy, "603" declined, "603-S" cancelled by the client, "402" insufficient funds, "404" invalid number, "423" blocked, "480" temporarily unavailable, "484" / "503" destination unavailable, "OTHER"
Parameteradd_to_chat Typeboolean Requiredno Default— DescriptionAdd a call event to the employee's chat
Parametervote Typenumber Requiredno Default— DescriptionCall rating: 1–5. Saved to the CALL_VOTE field (rating, shown as stars) in the Call statistics section. The uppercase key VOTE is also accepted

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/CALL_ID/finish \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "duration": 120,
    "statusCode": "200"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/CALL_ID/finish \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "duration": 120,
    "statusCode": "200"
  }'

JavaScript — personal key

javascript 
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.com/v1/calls/${callId}/finish`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    duration: 120,
    statusCode: '200',
  }),
})

const { success, data } = await res.json()
console.log('Activity:', data.crmActivityId)

JavaScript — OAuth application

javascript 
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.com/v1/calls/${callId}/finish`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    duration: 120,
    statusCode: '200',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe finished call
Fielddata.callId Typestring DescriptionCall identifier
Fielddata.externalCallId Typestring | null DescriptionExternal identifier passed at registration
Fielddata.portalUserId Typenumber DescriptionBitrix24 user ID
Fielddata.phoneNumber Typestring DescriptionPhone number
Fielddata.portalNumber Typestring DescriptionLine number in the Bitrix24 account
Fielddata.incoming Typestring DescriptionCall type: "1" — outbound, "2" — inbound, "3" — inbound with redirection, "4" — callback, "5" — informational
Fielddata.callDuration Typenumber DescriptionDuration in seconds
Fielddata.callStartDate Typeobject DescriptionCall start date. Returned as an empty object {} — see specifics
Fielddata.callStatus Typenumber DescriptionCompletion status
Fielddata.callVote Typenumber DescriptionCall rating
Fielddata.cost Typenumber DescriptionCall cost
Fielddata.costCurrency Typestring DescriptionCost currency
Fielddata.callFailedCode Typestring DescriptionThe passed statusCode
Fielddata.callFailedReason Typestring DescriptionText description of the completion reason
Fielddata.restAppId Typenumber | null DescriptionApplication ID
Fielddata.restAppName Typestring | false DescriptionApplication name
Fielddata.crmActivityId Typenumber | false DescriptionID of the created activity. false if no entity is linked
Fielddata.comment Typestring | null DescriptionComment on the call
Fielddata.id Typenumber DescriptionInternal ID of the call record
Fielddata.errors Typeobject | null DescriptionErrors that did not interrupt completion (e.g. activityCreation)
Fielddata.crmEntityType Typestring DescriptionType of the linked CRM entity (only when a link exists)
Fielddata.crmEntityId Typenumber DescriptionID of the linked CRM entity (only when a link exists)

Response example

HTTP 200 — the call is finished and the activity is created:

JSON 
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "externalCallId": null,
    "portalUserId": 1,
    "phoneNumber": "+12025550123",
    "portalNumber": "REST_APP:",
    "incoming": "2",
    "callDuration": 120,
    "callStartDate": {},
    "callStatus": 1,
    "callVote": 0,
    "cost": 0,
    "costCurrency": "",
    "callFailedCode": "200",
    "callFailedReason": "",
    "restAppId": null,
    "restAppName": false,
    "crmActivityId": 7995,
    "comment": null,
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069,
    "id": 61
  }
}

Error response example

400 — required parameters are missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (positive integer), duration (number ≥ 0, seconds)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionuserId is missing or is not recognized as a positive integer, or duration is missing or is not recognized as a non-negative number
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the telephony scope
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (text in error.message)
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

callStartDate is always returned as an empty object {}. See the actual call start date in the statistics.

crmActivityId: false when no link exists. The data.errors.activityCreation field returns a text description of the reason. The call is still considered finished.

The statusCode value affects the label in CRM. Passing it explicitly lets you record the completion reason independently of the duration.

See also