Admin API: traffic sources

The methods on this page do the same as the Sources («Источники») section in the panel: they create traffic sources, change their tokens and postback, and apply parameters to campaigns. All methods require a token with Full access («Полный доступ») (full). Authorization is described on the Admin API: overview and authorization page, and the request format and common error codes on the Request, response and error format page.

Source object

The list, read, create and update methods return a source in this form:

Token

An element of the tokens array. The array holds up to 128 tokens.

Leading and trailing spaces in name and param are dropped.

Postback row

An element of the postbacks array. The array holds up to 20 rows.

A postback address is a full http:// or https:// address up to 2048 characters, without spaces or line breaks. Curly braces are allowed only around macros.

In the single mode, postback_url is sent and the postbacks rows are not used. In the per_status mode, the postbacks rows with a matching status are sent and postback_url is not used.

Secrets

The values of postback_secret and capi_token cannot be read through the API: responses contain *** instead. You can change or delete a secret with the Update a source method.

Template catalog

Get the template catalog

GET /api/v1/traffic-source-templates

Returns the source template catalog. No parameters.

Response — code 200 and an object:

Sources

List sources

GET /api/v1/traffic-sources

Returns all of the team's sources. No parameters.

Response — code 200 and an array of source objects, newest first. There is no pagination.

Get a source

GET /api/v1/traffic-sources/{id}

Returns one source. {id} in the path is the source ID.

Response — code 200 and a source object.

Errors: 400 bad_request — {id} is not a UUID, 404 not_found — the source does not exist.

Create a source

POST /api/v1/traffic-sources

Creates a source from a catalog template or with the fields from the request.

If template_id is passed, the tokens, cost_model and postback_url fields are taken from the template, and the values from the request are ignored. The postback mode becomes single, and the postbacks rows are empty. For a template with setup_required, the postback address stays empty: set it with the Update a source method.

Response — code 201 and the created source object.

curl -X POST https://panel.example.com/api/v1/traffic-sources \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Facebook Ads","template_id":"facebook","template_version":1}'

Errors:

Postback errors come with code 400, name and token errors with code 422. Postback error texts are covered on the S2S postback to the source page, token error texts on the Source tokens page.

Update a source

PUT /api/v1/traffic-sources/{id}

Saves a source. {id} in the path is the source ID. The body replaces the record, so pass the whole source: get it with the Get a source method, change the fields you need and send it back. Secrets shown as *** are kept.

The template_id and template_version fields are not changed by this method.

Response — code 200 and a source object. The new tokens apply to clicks of all the source's campaigns right away. The parameters in campaign links do not change — that is what applying parameters is for.

Errors: the same 400 and 422 as on creation, 400 bad_request — {id} is not a UUID, 404 not_found — the source does not exist.

Delete a source

DELETE /api/v1/traffic-sources/{id}

Deletes a source. Campaigns stay, and their source field becomes empty. {id} in the path is the source ID.

Response — code 204 with no body.

Errors: 400 bad_request — {id} is not a UUID, 404 not_found — the source does not exist.

Applying parameters to campaigns

Applying takes two requests: first a preview, then the commit. The merge rules are described on the Applying a source to campaigns page.

Get a preview of the changes

POST /api/v1/traffic-sources/{id}/apply/preview

Shows how the source's saved tokens will change the parameters of each campaign with this source. Nothing changes in the campaigns. No request body is needed; {id} in the path is the source ID.

Response — code 200 and an object:

Errors:

Apply a preview

POST /api/v1/traffic-sources/{id}/apply

Writes the parameters from the preview's after field into the campaigns. {id} in the path is the source ID.

A preview can be applied only with a token of the same user who requested it.

curl -X POST https://panel.example.com/api/v1/traffic-sources/3f6c1c1e-8a52-4a4b-9c0d-2b7e5d1a9f10/apply \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"preview_id":"b1d7a0c4-52e3-4c8f-a6b9-0e4f7d2c3a15"}'

Response — code 200 and an object:

{
  "updated": 1,
  "total": 2,
  "outcomes": [
    {"id": "7a1e0f3b-6c2d-4e58-b9a1-3d5c8e2f4a60", "state": "updated"},
    {"id": "c4b2d9e1-0f7a-4b36-8d5e-1a9c6f3b2e74", "state": "conflict"}
  ]
}

updated is the number of updated campaigns, total is the number of campaigns in the preview. state values:

For campaigns with the conflict and unavailable outcomes, get a new preview and apply it. A repeated request with the same preview_id returns the saved result and changes nothing.

Errors: