For AI agents: markdown of this page — /docs-content-en/entities/crm-traces/v3-create.md documentation index — /llms.txt

The method is rolling out in update crm 26.2000.0. It is not available on every Bitrix24 account. If the method is not yet available on your account, the API returns 422 METHOD_NOT_YET_AVAILABLE — this indicates that the update has not reached the account yet, rather than an integration error.

Create an analytics trace

Endpoint: POST /v1/crm-traces

Records a visit with its analytics source and links it to CRM records. Send the fields at the JSON root.

This operation requires the crm-tracking-v3 flag and the REST v3 analytics capability enabled in the Bitrix24 account. The key needs the crm scope.

Writes require a READWRITE key.

Request body fields

Field Type Required Description
FieldsourceId Typenumber Requiredyes DescriptionActive analytics source ID. Obtain it from the Bitrix24 account administrator. This is not a lead source dictionary ID.
Fieldentities Typearray Requiredno DescriptionCRM links. Bitrix24 requires 1 to 50 links in total to create a trace.
Fieldentities[].type Typestring Requiredyes DescriptionType: LEAD, DEAL, CONTACT, COMPANY, QUOTE.
Fieldentities[].id Typenumber or string Requiredyes DescriptionPositive record ID. Use leads, deals, contacts, companies, or quotes.
FieldisMobile Typeboolean Requiredno DescriptionWhether the visit used a mobile device. Omitted means false.
Fieldutm Typeobject Requiredno DescriptionTags source, medium, campaign, content, term. Each is an optional string.
Fieldpages Typearray Requiredno DescriptionVisited pages, up to 10.
Fieldpages[].url Typestring Requiredyes DescriptionAbsolute http or https address, up to 1000 characters.
Fieldpages[].title Typestring Requiredno DescriptionPage title, up to 255 characters.
Fieldpages[].time Typestring Requiredno DescriptionISO 8601 date and time, such as 2026-10-28T10:00:00+00:00. Do not use a Unix timestamp.
Fieldchannels Typearray Requiredno DescriptionVisit channels, up to 20.
Fieldchannels[].code Typestring Requiredyes DescriptionChannel code, such as form, call, mail, site.
Fieldchannels[].value Typestring Requiredno DescriptionChannel value, up to 255 characters.

Required nested fields apply to each supplied array item. Bitrix24 validates count and length limits. The trace and sourceId fields are mutually exclusive.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-traces" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":2,"entities":[{"type":"DEAL","id":11}],"isMobile":false,"utm":{"source":"vibeprobe","campaign":"x"},"pages":[{"url":"https://example.com/p","title":"VIBE-PROBE page","time":"2026-10-28T10:00:00+00:00"}],"channels":[{"code":"form","value":"5"}]}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-traces" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":2,"entities":[{"type":"DEAL","id":11}],"isMobile":false,"utm":{"source":"vibeprobe","campaign":"x"},"pages":[{"url":"https://example.com/p","title":"VIBE-PROBE page","time":"2026-10-28T10:00:00+00:00"}],"channels":[{"code":"form","value":"5"}]}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-traces', {
  "method": "POST",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "sourceId": 2,
  "entities": [
    {
      "type": "DEAL",
      "id": 11
    }
  ],
  "isMobile": false,
  "utm": {
    "source": "vibeprobe",
    "campaign": "x"
  },
  "pages": [
    {
      "url": "https://example.com/p",
      "title": "VIBE-PROBE page",
      "time": "2026-10-28T10:00:00+00:00"
    }
  ],
  "channels": [
    {
      "code": "form",
      "value": "5"
    }
  ]
})
})
const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-traces', {
  "method": "POST",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "sourceId": 2,
  "entities": [
    {
      "type": "DEAL",
      "id": 11
    }
  ],
  "isMobile": false,
  "utm": {
    "source": "vibeprobe",
    "campaign": "x"
  },
  "pages": [
    {
      "url": "https://example.com/p",
      "title": "VIBE-PROBE page",
      "time": "2026-10-28T10:00:00+00:00"
    }
  ],
  "channels": [
    {
      "code": "form",
      "value": "5"
    }
  ]
})
})
const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata.id Typenumber DescriptionCreated trace ID. Read the full record: Get an analytics trace.

Response example

HTTP status: 201 Created.

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

Error response example

400: both creation formats supplied.

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "trace and sourceId are mutually exclusive"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionRequired request fields are missing.
HTTP400 CodeINVALID_PARAMS DescriptionInvalid request type or shape, or an invalid ID.
HTTP403 CodeSCOPE_DENIED DescriptionMissing crm scope.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe platform flag is off or RestV3Tracking is not enabled on the Bitrix24 portal. error.release is crm 26.2000.0.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid Bitrix24 response.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only.
HTTP403 CodeBITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION DescriptionInsufficient permissions for linked CRM records.
HTTP400 CodeBITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION DescriptionBitrix24 rejected the source, channel, links, or visit data. Details appear in error.validation.

Other Bitrix24 refusal codes, statuses and messages are preserved. See Errors for common failures.

Known specifics

The sourceId field selects this format. A request with trace uses the existing creation format regardless of the flag. Bitrix24 validates record update permissions and source eligibility during creation.

See also