Create a submission (draft)

POST /api/v1/submissions

https://app.tanba-ooh.kz/api/v1/submissions

Технический текст справочника написан на английском.

Scope write:submissions. Upload the media next; moderation and approval stay with the authority.

Аутентификация

Ключ API в заголовке Authorization или сессия консоли.

Право доступа: write:submissions

Тело запроса

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`advertiser_name`	string	да	Name of the advertiser, up to 300 characters.	`"Example Advertising LLP"`
`advertiser_bin`	string		Business identification number of the advertiser, 12 digits; optional.	`"123456789012"`
`period_from`	string (date)	да	First day of the campaign.	`"2026-11-01"`
`period_to`	string (date)	да	Last day of the campaign.	`"2026-11-30"`
`structure_ids`	array of string (uuid)	да	Structures the approval is requested for. Operators may name up to 200 of their own structures, agencies up to 2000 structures of any operators. Together with `structure_set_ids` this is the whole list: sending either replaces the current structures.	`["0b6f9d0e-6c1e-4a6a-9d55-0f8a6a6f3c11"]`
`structure_set_ids`	array of string (uuid)		Saved structure sets of the organisation, expanded into explicit structures; a structure retired since the set was saved is left out. The limit on the number of structures counts the expanded list.	`["5d3f3e0a-2a53-4b3c-8d0a-6f63b4d9a111"]`
`channel`	string		Where the creative comes from. `programmatic` is for creatives submitted by an exchange partner. direct, programmatic
`external_refs`	object		Identifiers of the exchange partner that submitted the creative. Unknown keys are refused. Only with channel `programmatic`.
`external_refs.crid`	string		Creative id in the partner's system.	`"cr-4711"`
`external_refs.adomain`	array of string		Domains of the advertiser, as in OpenRTB `adomain`.	`["example.com"]`
`external_refs.dsp`	string		Identifier of the demand-side platform.	`"dsp-one"`
`external_refs.ssp`	string		Identifier of the supply-side platform.	`"ssp-one"`
`fast_track`	boolean		Ask for the priority queue. The submission gets a review deadline of a few working hours (`review_due_at`); the review itself stays a human decision. Only with channel `programmatic`.	`true`
`category_id`	integer		Product category of the advertised product, an id from `GET /api/v1/categories`. It may be omitted while the draft is built, and is required before the submission is sent for review.	`1004`
`declared_daily_plays`	object		Plays per day the operator declares per chosen structure, keyed by structure id. The `declared_vs_actual` city event compares the plays of a full day with it (default band of 30 %).

Пример

{
  "advertiser_name": "Example Advertising LLP",
  "advertiser_bin": "123456789012",
  "period_from": "2026-11-01",
  "period_to": "2026-11-30",
  "structure_ids": [
    "0b6f9d0e-6c1e-4a6a-9d55-0f8a6a6f3c11"
  ],
  "structure_set_ids": [
    "5d3f3e0a-2a53-4b3c-8d0a-6f63b4d9a111"
  ],
  "channel": "programmatic",
  "external_refs": {
    "crid": "cr-4711",
    "adomain": [
      "example.com"
    ],
    "dsp": "dsp-one",
    "ssp": "ssp-one"
  },
  "fast_track": true,
  "category_id": 1004,
  "declared_daily_plays": {}
}

Ответы

201 The draft.

`application/json`

Submission

Имя	Тип	Обязательный	Описание	Пример
`id`	string (uuid)	да	Identifier of the submission.	`"6f1c0d3e-52a4-4b57-9a7e-0c3a1b9d2e44"`
`number`	string	да	Number of the submission.	`"SUB-2026-000087"`
`state`	string	да	Current state of the submission.	`"draft"`
`advertiser_name`	string	да	Name of the advertiser.	`"Example Advertising LLP"`
`period_from`	string \| null	да	First day of the campaign; null if not set yet.	`"2026-11-01"`
`period_to`	string \| null	да	Last day of the campaign; null if not set yet.	`"2026-11-30"`
`declared_daily_plays`	object		Plays per day declared for each structure, keyed by structure identifier.
`category_id`	integer \| null		Advertiser product category, an id from `GET /api/v1/categories` (IAB Ad Product Taxonomy 2.0, tiers 1 and 2). Required to send a new submission for review; null on submissions that were already in review when categories were introduced.	`1004`
`category`	oneOf		The category with its names in the three console languages, or null when none is set.
`channel`	string		Where the creative comes from. direct, programmatic
`fast_track`	boolean		Whether the submission asked for the priority queue.	`true`
`external_refs`	object		Identifiers of the exchange partner that submitted the creative. Unknown keys are refused. Only with channel `programmatic`.
`external_refs.crid`	string		Creative id in the partner's system.	`"cr-4711"`
`external_refs.adomain`	array of string		Domains of the advertiser, as in OpenRTB `adomain`.	`["example.com"]`
`external_refs.dsp`	string		Identifier of the demand-side platform.	`"dsp-one"`
`external_refs.ssp`	string		Identifier of the supply-side platform.	`"ssp-one"`
`review_due_at`	string \| null		Deadline of a fast-track review in Almaty time, counted in working hours; null without fast-track or before the submission is sent.	`"2026-10-19T11:00:00+05:00"`

Пример

{
  "id": "6f1c0d3e-52a4-4b57-9a7e-0c3a1b9d2e44",
  "number": "SUB-2026-000087",
  "state": "draft",
  "advertiser_name": "Example Advertising LLP",
  "period_from": "2026-11-01",
  "period_to": "2026-11-30",
  "declared_daily_plays": {},
  "category_id": 1004,
  "category": {
    "id": 1004,
    "parent_id": 1002,
    "tier": 2,
    "name": {
      "en": "Beer",
      "ru": "Пиво",
      "kk": "Сыра"
    }
  },
  "channel": "programmatic",
  "fast_track": true,
  "external_refs": {
    "crid": "cr-4711",
    "adomain": [
      "example.com"
    ],
    "dsp": "dsp-one",
    "ssp": "ssp-one"
  },
  "review_due_at": "2026-10-19T11:00:00+05:00"
}

Ошибки

Ошибки приходят документом problem (application/problem+json) со стабильным полем code.

Статус	Значение
401	Нет действительной сессии или ключа API (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	Роль или право ключа этого не допускает (`forbidden`, `key_scope_denied`, `key_route_denied`).
422	Ошибки полей (`validation_failed`).
default	Ошибка в виде документа problem.

Примеры кода

curl

curl -X POST 'https://app.tanba-ooh.kz/api/v1/submissions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "advertiser_name": "Example Advertising LLP",
  "advertiser_bin": "123456789012",
  "period_from": "2026-11-01",
  "period_to": "2026-11-30",
  "structure_ids": [
    "0b6f9d0e-6c1e-4a6a-9d55-0f8a6a6f3c11"
  ],
  "structure_set_ids": [
    "5d3f3e0a-2a53-4b3c-8d0a-6f63b4d9a111"
  ],
  "channel": "programmatic",
  "external_refs": {
    "crid": "cr-4711",
    "adomain": [
      "example.com"
    ],
    "dsp": "dsp-one",
    "ssp": "ssp-one"
  },
  "fast_track": true,
  "category_id": 1004,
  "declared_daily_plays": {}
}'

Python

import requests

response = requests.post(
    "https://app.tanba-ooh.kz/api/v1/submissions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "advertiser_name": "Example Advertising LLP",
        "advertiser_bin": "123456789012",
        "period_from": "2026-11-01",
        "period_to": "2026-11-30",
        "structure_ids": [
            "0b6f9d0e-6c1e-4a6a-9d55-0f8a6a6f3c11",
        ],
        "structure_set_ids": [
            "5d3f3e0a-2a53-4b3c-8d0a-6f63b4d9a111",
        ],
        "channel": "programmatic",
        "external_refs": {
            "crid": "cr-4711",
            "adomain": [
                "example.com",
            ],
            "dsp": "dsp-one",
            "ssp": "ssp-one",
        },
        "fast_track": True,
        "category_id": 1004,
        "declared_daily_plays": {},
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "advertiser_name": "Example Advertising LLP",
  "advertiser_bin": "123456789012",
  "period_from": "2026-11-01",
  "period_to": "2026-11-30",
  "structure_ids": [
    "0b6f9d0e-6c1e-4a6a-9d55-0f8a6a6f3c11"
  ],
  "structure_set_ids": [
    "5d3f3e0a-2a53-4b3c-8d0a-6f63b4d9a111"
  ],
  "channel": "programmatic",
  "external_refs": {
    "crid": "cr-4711",
    "adomain": [
      "example.com"
    ],
    "dsp": "dsp-one",
    "ssp": "ssp-one"
  },
  "fast_track": true,
  "category_id": 1004,
  "declared_daily_plays": {}
}`)
	req, err := http.NewRequest("POST", "https://app.tanba-ooh.kz/api/v1/submissions", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}