# Sales-intelligence traces

A trace stores a site visitor's journey and acquisition source and is bound to CRM leads, deals, contacts, companies or quotes.

Bitrix24 API: `crm.tracking.trace.list`, `crm.tracking.trace.get`, `crm.tracking.trace.add`, `crm.tracking.trace.delete`
Scope: `crm`

## Operations

- [List traces (REST v3, rolling out)](./crm-traces/v3-list.md) — `GET /v1/crm-traces`
- [Read a trace (REST v3, rolling out)](./crm-traces/v3-get.md) — `GET /v1/crm-traces/:id`
- [Create with a source (REST v3, rolling out)](./crm-traces/v3-create.md) — `POST /v1/crm-traces`
- [Delete a complete trace (REST v3, rolling out)](./crm-traces/v3-delete.md) — `DELETE /v1/crm-traces/:id`

- [Create a trace (REST v1)](./crm-traces/create.md) — `POST /v1/crm-traces`
- [Delete a trace (flag off)](./crm-traces/delete.md) — `DELETE /v1/crm-traces/:id`

## Key fields

Body fields of [`POST /v1/crm-traces`](./crm-traces/create.md).

| Field | Description |
|------|---------|
| `sourceId` | Explicit source for [REST v3 creation](./crm-traces/v3-create.md); mutually exclusive with `trace` |
| `trace` | A trace object or a string containing a JSON object. The site tracker `b24Tracker.guest.getTrace()` returns the string |
| `trace.url` | Address of the page the visitor was on |
| `trace.ref` | Address the visitor came to the page from |
| `trace.tags.list` | UTM tags, for example `utm_source` and `utm_campaign` |
| `entities[].type` | CRM record type: `LEAD`, `DEAL`, `CONTACT`, `COMPANY`, `QUOTE` |
| `entities[].id` | CRM record ID. List: [`GET /v1/leads`](./leads/list.md), [`GET /v1/deals`](./deals/list.md), [`GET /v1/contacts`](./contacts/list.md), [`GET /v1/companies`](./companies/list.md), [`GET /v1/quotes`](./quotes/list.md) |

The create response contains only `data.id` — the trace identifier. You need it to delete the trace.

## What to know before you start

1. **Writes require a key with write access.** A read-only key can read traces; POST and DELETE return `403 WRITE_BLOCKED_READONLY_KEY`.
2. **Legacy creation checks bindings before writing.** Every record from `entities` is read before the trace is created. If at least one record does not exist, the response is `404 ENTITY_NOT_FOUND`, and the trace is not created.
3. **Legacy creation allows a trace without bindings.** Without `entities` or with an empty array, an unbound trace is created.
4. **Trace reads are rolling out.** List and get use REST v3, the `crm-tracking-v3` platform flag and the Bitrix24 RestV3Tracking feature. An unavailable operation returns `422 METHOD_NOT_YET_AVAILABLE` with `error.release`.
5. **Deletion depends on the platform flag.** With `crm-tracking-v3` off, legacy deletion is idempotent and can remove only accessible bindings. With the flag on, REST v3 deletes the complete trace, requires update access to all bound records and returns `404 ENTITY_NOT_FOUND` for a missing trace.

## Typical scenario

A form on a website creates a lead and saves where the visitor came from:

1. On the site page, get the trace from `b24Tracker.guest.getTrace()`.
2. Create a lead: [`POST /v1/leads`](./leads/create.md). Its identifier is `data.id`.
3. Create a trace bound to the lead: [`POST /v1/crm-traces`](./crm-traces/create.md) with the body `{"trace": ..., "entities": [{"type": "LEAD", "id": <lead id>}]}`. Save the trace's `data.id`.
4. To delete the trace, call [`DELETE /v1/crm-traces/:id`](./crm-traces/delete.md) with the saved identifier.

## Limits

| Limit | Value |
|-------|----------|
| Bitrix24 calls per legacy create | one read for each unique record from `entities` and one trace creation. Repeats of the same record in `entities` are read once |
| Request body size | up to 1 MiB |
| Request rate | shared Vibecode API limit — see [Request limits](/docs/keys-auth#request-limits) |

## See also

- [Leads](/docs/entities/leads)
- [Deals](/docs/entities/deals)
- [Limits and optimization](/docs/optimization)
- [Errors](/docs/errors)