# Create a trace

`POST /v1/crm-traces`

Bitrix24 method: `crm.tracking.trace.add`. Scope `crm`, READWRITE key.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| trace | object or string | Yes | A JSON trace object or a string containing a JSON object. Arrays and scalars are refused. |
| entities | array | No | CRM bindings. An omitted or empty array legally leaves the trace unbound. |
| entities[].type | string | Yes | LEAD, DEAL, CONTACT, COMPANY or QUOTE. |
| entities[].id | number or string | Yes | A positive safe integer id of an existing record. |

A trace object is serialized without renaming its keys. `b24Tracker.guest.getTrace()` returns a ready-to-use string. Bitrix24 reads `url`, `gid`, `device.isMobile`, `pages.list` with `[url, timestamp, title]` tuples, `tags.ts`, `tags.list` with UTM tags, `previous.list`, and `channels` with `code` and `value`. The `ref` key supplies the referrer, and `client` supplies the analytics client identifier. The minimal object may be empty.

```bash
curl -X POST 'https://vibecode.bitrix24.com/v1/crm-traces'   -H 'X-Api-Key: YOUR_API_KEY' -H 'Content-Type: application/json'   -d '{"trace":{"url":"https://example.com/form","tags":{"list":{"utm_source":"newsletter"}}},"entities":[{"type":"LEAD","id":123}]}'
```

## Response

HTTP 201. `data.id` is the numeric id of the created trace.

```json
{"success":true,"data":{"id":42}}
```

## Errors

| HTTP | Code | Reason |
|---|---|---|
| 400 | MISSING_REQUIRED_FIELDS | Missing trace. |
| 400 | INVALID_PARAMS | Invalid JSON, scalar, array or binding. |
| 403 | SCOPE_DENIED | Missing crm scope. |
| 403 | WRITE_BLOCKED_READONLY_KEY | The key prohibits writes. |
| 403 | BITRIX_ACCESS_DENIED | Bitrix24 refuses record read or update access. |
| 404 | ENTITY_NOT_FOUND | CRM record absent during the pre-read. |
| 422 | BITRIX_ERROR | Bitrix24 business refusal with its original message. |
| 502 | BITRIX_UNAVAILABLE | Invalid Bitrix24 response. |

The pre-read happens before trace creation. Bitrix24 checks update access when adding the trace. The record may disappear between validation and creation.

[All operations](../crm-traces.md) · [Delete a trace](./delete.md)