For AI agents: markdown of this page — /docs-content-en/entities/crm-tracking/ad-expenses-start.md documentation index — /llms.txt

The method ships in the crm 26.2100.0 update and is not yet available on all Bitrix24 accounts. If the method is not enabled yet, the API returns 422 METHOD_NOT_YET_AVAILABLE.

Run a step of the advertising expense report

POST /v1/crm-tracking/sources/:id/ad-expenses

Start or continue building an advertising expense report for a period. Each request runs one step.

Requires the crm scope, the crm-tracking-v3 flag, and method availability in the Bitrix24 account. A READONLY key cannot run this request.

Parameters

Parameter Type Required Default Description
Parameterid (path) Typeinteger Requiredyes Default— DescriptionPositive source ID from the source list.

Request body fields

Field Type Required Description
FielddateFrom Typestring Requiredyes DescriptionPeriod start, YYYY-MM-DD.
FielddateTo Typestring Requiredyes DescriptionPeriod end, YYYY-MM-DD.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-tracking/sources/42/ad-expenses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dateFrom":"2026-10-01","dateTo":"2026-10-07"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-tracking/sources/42/ad-expenses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dateFrom":"2026-10-01","dateTo":"2026-10-07"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-tracking/sources/42/ad-expenses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dateFrom: '2026-10-01', dateTo: '2026-10-07' }),
})
const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-tracking/sources/42/ad-expenses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ dateFrom: '2026-10-01', dateTo: '2026-10-07' }),
})
const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typeobject DescriptionReport progress.
Fielddata.complete Typeboolean DescriptionWhether the report is complete.
Fielddata.label Typestring or null DescriptionCurrent step label or null. Its language depends on the Bitrix24 account.

Response example

JSON 
{
  "success": true,
  "data": {
    "complete": false,
    "label": null
  }
}

Error response example

400 — the source does not support advertising reports:

JSON 
{
  "success": false,
  "error": {
    "code": "CRM_TRACKING_AD_PROVIDER_UNSUPPORTED",
    "message": "CRM_TRACKING_AD_PROVIDER_UNSUPPORTED"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid source ID or field type.
HTTP400 CodeBITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION DescriptionDates are missing, or Bitrix24 rejected the parameter values.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP400 CodeCRM_TRACKING_AD_PROVIDER_UNSUPPORTED DescriptionThe source does not support the advertising operation.
HTTP404 CodeENTITY_NOT_FOUND DescriptionSource not found.
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope.
HTTP403 CodeBITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION DescriptionInsufficient permissions on the Bitrix24 portal.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA READONLY key cannot build the report.
HTTP401 CodeTOKEN_MISSING DescriptionBitrix24 access is not configured for the key.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe flag is off or the method is not enabled in the portal. error.release is crm 26.2100.0.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response structure.

Other Bitrix24 refusal codes, statuses, and messages are preserved. For common API errors, see Errors.

Known specifics

If complete is false, run the next step by repeating the POST request with the same period. Reading progress alone does not continue building the report.

See also