[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fcrm-traces\u002Fcreate":3,"docs-tabs-entities\u002Fcrm-traces\u002Fcreate":6},{"content":4,"lastmod":5},"## Create a trace\n\n`POST \u002Fv1\u002Fcrm-traces`\n\nCreates a sales-intelligence trace and binds it to CRM records. Call it after creating a lead or another record to save where the visitor came from.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `trace` | object \\| string | yes | A trace object or a string containing a JSON object. An array, a number, `null` and a string without a JSON object are rejected with `400 INVALID_PARAMS` |\n| `entities` | array | no | Bindings to CRM records. Without the array or with an empty array, an unbound trace is created |\n| `entities[].type` | string | yes | Record type: `LEAD`, `DEAL`, `CONTACT`, `COMPANY` or `QUOTE` |\n| `entities[].id` | number \\| string | yes | ID of an existing record — a positive integer; a string of digits is also accepted. List: [`GET \u002Fv1\u002Fleads`](\u002Fdocs\u002Fentities\u002Fleads\u002Flist), [`GET \u002Fv1\u002Fdeals`](\u002Fdocs\u002Fentities\u002Fdeals\u002Flist), [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Flist), [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies\u002Flist), [`GET \u002Fv1\u002Fquotes`](\u002Fdocs\u002Fentities\u002Fquotes\u002Flist) |\n\nA `trace` object is passed without renaming its keys; a string is passed as is. The site tracker `b24Tracker.guest.getTrace()` returns a ready-to-use string. Sales intelligence uses the following trace keys: `url`, `ref` — the address the visitor came from, `client` — the analytics client identifier, `gid`, `device.isMobile`, `pages.list` with `[url, timestamp, title]` triples, `tags.ts`, `tags.list` with UTM tags, `previous.list`, `channels` with the `code` and `value` fields. The object may be empty: `{\"trace\": {}}` creates a trace.\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 '{\n    \"trace\": {\n      \"url\": \"https:\u002F\u002Fexample.com\u002Fform\",\n      \"ref\": \"https:\u002F\u002Fexample.com\u002Fnews\",\n      \"tags\": { \"list\": { \"utm_source\": \"newsletter\", \"utm_campaign\": \"autumn\" } }\n    },\n    \"entities\": [{ \"type\": \"LEAD\", \"id\": 123 }]\n  }'\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 '{\n    \"trace\": {\n      \"url\": \"https:\u002F\u002Fexample.com\u002Fform\",\n      \"ref\": \"https:\u002F\u002Fexample.com\u002Fnews\",\n      \"tags\": { \"list\": { \"utm_source\": \"newsletter\", \"utm_campaign\": \"autumn\" } }\n    },\n    \"entities\": [{ \"type\": \"LEAD\", \"id\": 123 }]\n  }'\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    trace: {\n      url: 'https:\u002F\u002Fexample.com\u002Fform',\n      ref: 'https:\u002F\u002Fexample.com\u002Fnews',\n      tags: { list: { utm_source: 'newsletter', utm_campaign: 'autumn' } },\n    },\n    entities: [{ type: 'LEAD', id: 123 }],\n  }),\n})\n\nconst { data } = await res.json()\nconsole.log('Trace ID:', data.id)\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    trace: {\n      url: 'https:\u002F\u002Fexample.com\u002Fform',\n      ref: 'https:\u002F\u002Fexample.com\u002Fnews',\n      tags: { list: { utm_source: 'newsletter', utm_campaign: 'autumn' } },\n    },\n    entities: [{ type: 'LEAD', id: 123 }],\n  }),\n})\n\nconst { data } = await res.json()\nconsole.log('Trace ID:', data.id)\n```\n\n## Response fields\n\nHTTP status `201 Created`.\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | The created trace |\n| `data.id` | number | Trace identifier. Needed for [deletion](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fdelete) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 2025\n  }\n}\n```\n\n## Error response example\n\n404 — a CRM record from `entities` was not found, the trace was not created:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Not found\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `MISSING_REQUIRED_FIELDS` | The body has no `trace`, or the body is not a JSON object |\n| 400 | `INVALID_PARAMS` | `trace` is neither an object nor a string with a JSON object, the body root or an `entities` element has an extra key, `entities` is not an array, `entities[].type` is unknown, or `entities[].id` is not a positive integer |\n| 404 | `ENTITY_NOT_FOUND` | A CRM record from `entities` was not found. The trace is not created |\n| 403 | `BITRIX_ACCESS_DENIED` | No permission to read or update a CRM record from `entities` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the trace creation. The error text is returned in `error.message` |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned an invalid response to the record read or to the trace creation |\n| 403 | `SCOPE_DENIED` | The key does not have the `crm` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key works in read-only mode |\n| 401 | `TOKEN_MISSING` | The key has no configured tokens |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**Records are checked before creation.** All records from `entities` are read before the trace is created; duplicate records are read only once. If at least one record is not found or not accessible, the trace is not created. Permission to update a record is checked when the trace is created. The check does not protect against a record being deleted between the read and the trace creation.\n\n## See also\n\n- [Delete a trace](\u002Fdocs\u002Fentities\u002Fcrm-traces\u002Fdelete)\n- [Sales-intelligence traces](\u002Fdocs\u002Fentities\u002Fcrm-traces)\n- [Create a lead](\u002Fdocs\u002Fentities\u002Fleads\u002Fcreate)\n","2026-10-20",{},1795000318167]