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.

Authentication

API key in the Authorization header, or a console session.

Scope: write:submissions

Request body

`application/json`

Name	Type	Required	Description	Example
`advertiser_name`	string	yes	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)	yes	First day of the campaign.	`"2026-11-01"`
`period_to`	string (date)	yes	Last day of the campaign.	`"2026-11-30"`
`structure_ids`	array of string (uuid)	yes	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 %).

Example

{
  "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": {}
}

Responses

201 The draft.

`application/json`

Submission

Name	Type	Required	Description	Example
`id`	string (uuid)	yes	Identifier of the submission.	`"6f1c0d3e-52a4-4b57-9a7e-0c3a1b9d2e44"`
`number`	string	yes	Number of the submission.	`"SUB-2026-000087"`
`state`	string	yes	Current state of the submission.	`"draft"`
`advertiser_name`	string	yes	Name of the advertiser.	`"Example Advertising LLP"`
`period_from`	string \| null	yes	First day of the campaign; null if not set yet.	`"2026-11-01"`
`period_to`	string \| null	yes	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"`

Example

{
  "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"
}

Errors

Errors are problem documents (application/problem+json) with a stable code.

Status	Meaning
401	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
422	Field errors (`validation_failed`).
default	An error as a problem document.

Code samples

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))
}