[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fcrm-traces\u002Fv3-create":3,"docs-tabs-entities\u002Fcrm-traces\u002Fv3-create":6},{"content":4,"lastmod":5},"> **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.\n\n## Create an analytics trace\n\nEndpoint: `POST \u002Fv1\u002Fcrm-traces`\n\nRecords a visit with its analytics source and links it to CRM records. Send the fields at the JSON root.\n\n> 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.\n\nWrites require a `READWRITE` key.\n\n## Request body fields\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `sourceId` | number | yes | Active analytics source ID. Obtain it from the Bitrix24 account administrator. This is not a lead source dictionary ID. |\n| `entities` | array | no | CRM links. Bitrix24 requires 1 to 50 links in total to create a trace. |\n| `entities[].type` | string | yes | Type: `LEAD`, `DEAL`, `CONTACT`, `COMPANY`, `QUOTE`. |\n| `entities[].id` | number or string | yes | Positive record ID. Use [leads](\u002Fdocs\u002Fentities\u002Fleads\u002Flist), [deals](\u002Fdocs\u002Fentities\u002Fdeals\u002Flist), [contacts](\u002Fdocs\u002Fentities\u002Fcontacts\u002Flist), [companies](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist), or [quotes](\u002Fdocs\u002Fentities\u002Fquotes\u002Flist). |\n| `isMobile` | boolean | no | Whether the visit used a mobile device. Omitted means `false`. |\n| `utm` | object | no | Tags `source`, `medium`, `campaign`, `content`, `term`. Each is an optional string. |\n| `pages` | array | no | Visited pages, up to 10. |\n| `pages[].url` | string | yes | Absolute `http` or `https` address, up to 1000 characters. |\n| `pages[].title` | string | no | Page title, up to 255 characters. |\n| `pages[].time` | string | no | ISO 8601 date and time, such as `2026-10-28T10:00:00+00:00`. Do not use a Unix timestamp. |\n| `channels` | array | no | Visit channels, up to 20. |\n| `channels[].code` | string | yes | Channel code, such as `form`, `call`, `mail`, `site`. |\n| `channels[].value` | string | no | Channel value, up to 255 characters. |\n\nRequired nested fields apply to each supplied array item. Bitrix24 validates count and length limits. The `trace` and `sourceId` fields are mutually exclusive.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm-traces\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"sourceId\":2,\"entities\":[{\"type\":\"DEAL\",\"id\":11}],\"isMobile\":false,\"utm\":{\"source\":\"vibeprobe\",\"campaign\":\"x\"},\"pages\":[{\"url\":\"https:\u002F\u002Fexample.com\u002Fp\",\"title\":\"VIBE-PROBE page\",\"time\":\"2026-10-28T10:00:00+00:00\"}],\"channels\":[{\"code\":\"form\",\"value\":\"5\"}]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm-traces\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"sourceId\":2,\"entities\":[{\"type\":\"DEAL\",\"id\":11}],\"isMobile\":false,\"utm\":{\"source\":\"vibeprobe\",\"campaign\":\"x\"},\"pages\":[{\"url\":\"https:\u002F\u002Fexample.com\u002Fp\",\"title\":\"VIBE-PROBE page\",\"time\":\"2026-10-28T10:00:00+00:00\"}],\"channels\":[{\"code\":\"form\",\"value\":\"5\"}]}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm-traces', {\n  \"method\": \"POST\",\n  \"headers\": {\n    \"X-Api-Key\": \"YOUR_API_KEY\",\n    \"Content-Type\": \"application\u002Fjson\"\n  },\n  \"body\": JSON.stringify({\n  \"sourceId\": 2,\n  \"entities\": [\n    {\n      \"type\": \"DEAL\",\n      \"id\": 11\n    }\n  ],\n  \"isMobile\": false,\n  \"utm\": {\n    \"source\": \"vibeprobe\",\n    \"campaign\": \"x\"\n  },\n  \"pages\": [\n    {\n      \"url\": \"https:\u002F\u002Fexample.com\u002Fp\",\n      \"title\": \"VIBE-PROBE page\",\n      \"time\": \"2026-10-28T10:00:00+00:00\"\n    }\n  ],\n  \"channels\": [\n    {\n      \"code\": \"form\",\n      \"value\": \"5\"\n    }\n  ]\n})\n})\nconst result = await res.json()\nconsole.log(result)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm-traces', {\n  \"method\": \"POST\",\n  \"headers\": {\n    \"X-Api-Key\": \"YOUR_APP_KEY\",\n    \"Authorization\": \"Bearer USER_SESSION_TOKEN\",\n    \"Content-Type\": \"application\u002Fjson\"\n  },\n  \"body\": JSON.stringify({\n  \"sourceId\": 2,\n  \"entities\": [\n    {\n      \"type\": \"DEAL\",\n      \"id\": 11\n    }\n  ],\n  \"isMobile\": false,\n  \"utm\": {\n    \"source\": \"vibeprobe\",\n    \"campaign\": \"x\"\n  },\n  \"pages\": [\n    {\n      \"url\": \"https:\u002F\u002Fexample.com\u002Fp\",\n      \"title\": \"VIBE-PROBE page\",\n      \"time\": \"2026-10-28T10:00:00+00:00\"\n    }\n  ],\n  \"channels\": [\n    {\n      \"code\": \"form\",\n      \"value\": \"5\"\n    }\n  ]\n})\n})\nconst result = await res.json()\nconsole.log(result)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | `true` |\n| `data.id` | number | Created trace ID. Read the full record: [Get an analytics trace](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fv3-get). |\n\n## Response example\n\nHTTP status: `201 Created`.\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 1\n  }\n}\n```\n\n## Error response example\n\n400: both creation formats supplied.\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"trace and sourceId are mutually exclusive\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|---|---|---|\n| 400 | `MISSING_REQUIRED_FIELDS` | Required request fields are missing. |\n| 400 | `INVALID_PARAMS` | Invalid request type or shape, or an invalid ID. |\n| 403 | `SCOPE_DENIED` | Missing `crm` scope. |\n| 401 | `TOKEN_MISSING` | The key has no configured tokens. |\n| 422 | `METHOD_NOT_YET_AVAILABLE` | The platform flag is off or RestV3Tracking is not enabled on the Bitrix24 portal. `error.release` is `crm 26.2000.0`. |\n| 502 | `BITRIX_UNAVAILABLE` | Invalid Bitrix24 response. |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. |\n| 403 | `BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION` | Insufficient permissions for linked CRM records. |\n| 400 | `BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION` | Bitrix24 rejected the source, channel, links, or visit data. Details appear in `error.validation`. |\n\nOther Bitrix24 refusal codes, statuses and messages are preserved. See [Errors](\u002Fdocs\u002Ferrors) for common failures.\n\n## Known specifics\n\nThe `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.\n\n## See also\n\n- [List analytics traces](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fv3-list)\n- [Get an analytics trace](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fv3-get)\n- [Delete an analytics trace](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fv3-delete)\n","2026-10-28",{},1794739359836]