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

This method is rolling out with crm 26.2100.0. It is not available on every Bitrix24 account yet. If it is not available, the API returns 422 METHOD_NOT_YET_AVAILABLE. This is not an integration error: it means the update has not reached the account yet.

Connect an advertising account

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

Connects an advertising account to an end-to-end analytics source and returns the resulting connection settings.

Requires the crm scope, a READWRITE key, the crm-tracking-v3 flag enabled, and the method available in the Bitrix24 account.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPositive integer source ID from the sources list.

Request body fields

Field Type Required Description
FieldclientId Typestring Requiredyes DescriptionClient ID from the advertising accounts list.
FieldaccountId Typestring | null Requiredno DescriptionAdvertising account ID from the advertising accounts list.

Send fields at the JSON root. Query parameters and unknown body fields are not accepted. String lengths and provider-specific requirements are validated by Bitrix24.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-tracking/sources/2/ad-account" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"DUMMY_CLIENT"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-tracking/sources/2/ad-account" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"DUMMY_CLIENT"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-tracking/sources/2/ad-account', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ clientId: 'DUMMY_CLIENT' })
})
const { success, data } = await res.json()
console.log(data.sourceId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-tracking/sources/2/ad-account', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ clientId: 'DUMMY_CLIENT' })
})
const { success, data } = await res.json()
console.log(data.sourceId)

Response fields

Success returns HTTP 200 with JSON.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success.
Fielddata Typeobject DescriptionResulting connection settings.
Fielddata.sourceId Typenumber DescriptionSource ID from the sources list.
Fielddata.provider Typestring DescriptionAdvertising system code.
Fielddata.clientId Typestring | null DescriptionConnected client ID from the advertising accounts list or null.
Fielddata.accountId Typestring | null DescriptionConnected advertising account ID from the advertising accounts list or null.

Response example

Example response structure.

JSON 
{
  "success": true,
  "data": {
    "sourceId": 2,
    "provider": "google",
    "clientId": "DUMMY_CLIENT",
    "accountId": null
  }
}

Error response example

400 — the source does not support advertising account connections:

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionclientId is missing.
HTTP400 CodeINVALID_PARAMS DescriptionInvalid ID, incorrect field type, unknown body field, or non-object body.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionA query parameter was supplied.
HTTP400 CodeCRM_TRACKING_AD_PROVIDER_UNSUPPORTED DescriptionThe source does not support this advertising operation.
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key access mode blocks writes.
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe specified source was not found.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe flag is off or the method is not yet available in the Bitrix24 account.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an invalid response.

Other Bitrix24 refusal codes and messages are preserved. See Errors for shared API errors.

See also