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.

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

Authorization тақырыбындағы API кілті немесе консоль сеансы.

Рұқсат: 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	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.

Код мысалдары

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