Look up up to 500 creative files at once

POST /api/v1/creatives/lookup

https://app.tanba-ooh.kz/api/v1/creatives/lookup

Scope read:creatives. The same answer as the single lookup for each hash, in the order given and without repeats. A hash the caller may not see answers with an empty approvals list instead of 404.

Authentication

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

Scope: read:creatives

Request body

`application/json`

Name	Type	Required	Description	Example
`hashes`	array of string	yes	Lowercase hexadecimal SHA-256 values of media files.	`["2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17"]`

Example

{
  "hashes": [
    "2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17"
  ]
}

Responses

200 One answer per hash.

`application/json`

Name	Type	Required	Description	Example
`items`	array of object	yes	One entry per requested hash.
`items[].sha256`	string	yes	The hash that was asked for.	`"2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17"`
`items[].approvals`	array of CreativeEntry	yes	The approvals visible to the caller; empty when there are none.
`items[].approvals[].status`	string	yes	`valid`, `not_yet_valid`, `expired` and `revoked` describe an issued approval. `pending` and `rejected` describe a submission of the caller's own organisation that has no approval. valid, not_yet_valid, expired, revoked, pending, rejected
`items[].approvals[].approval_number`	string \| null	yes	Number of the approval; null for pending and rejected.	`"TNB-2026-123456"`
`items[].approvals[].submission_number`	string \| null	yes	Number of the submission; only filled for the caller's own submissions.	`"SUB-2026-000001"`
`items[].approvals[].valid_from`	string \| null (date)	yes	First day of the approval; for pending and rejected, the first day of the requested period.	`"2026-10-14"`
`items[].approvals[].valid_until`	string \| null (date)	yes	Last day of the approval; for pending and rejected, the last day of the requested period.	`"2026-11-13"`
`items[].approvals[].structures`	array of string	yes	Codes of the structures the approval covers.	`["ALM-0001", "ALM-0002"]`
`items[].approvals[].category_id`	integer \| null	yes	Product category: an id from `GET /api/v1/categories`.	`1004`
`items[].approvals[].duration_ms`	integer \| null	yes	Length of the video in milliseconds; null for images.	`15000`
`items[].approvals[].width`	integer \| null	yes	Width of the media in pixels.	`1920`
`items[].approvals[].height`	integer \| null	yes	Height of the media in pixels.	`1080`
`items[].approvals[].envelope_url`	string \| null (uri)	yes	Where to fetch the signed envelope (needs the same credentials); null without an approval.	`"https://app.tanba-ooh.kz/api/v1/approvals/TNB-2026-123456/envelope"`
`revocation_list_version`	integer \| null	yes	Version of the newest signed revocation list; null before the first one.	`42`

Example

{
  "items": [
    {
      "sha256": "2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17",
      "approvals": [
        {
          "status": "valid",
          "approval_number": "TNB-2026-123456",
          "submission_number": "SUB-2026-000001",
          "valid_from": "2026-10-14",
          "valid_until": "2026-11-13",
          "structures": [
            "ALM-0001",
            "ALM-0002"
          ],
          "category_id": 1004,
          "duration_ms": 15000,
          "width": 1920,
          "height": 1080,
          "envelope_url": "https://app.tanba-ooh.kz/api/v1/approvals/TNB-2026-123456/envelope"
        }
      ]
    }
  ],
  "revocation_list_version": 42
}

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/creatives/lookup' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "hashes": [
    "2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17"
  ]
}'

Python

import requests

response = requests.post(
    "https://app.tanba-ooh.kz/api/v1/creatives/lookup",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "hashes": [
            "2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17",
        ],
    },
)
print(response.status_code, response.text)

package main

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

func main() {
	body := strings.NewReader(`{
  "hashes": [
    "2419fe2d001c9185b3b903283894a5d955f45a57d1eaf1c6b787759650f00a17"
  ]
}`)
	req, err := http.NewRequest("POST", "https://app.tanba-ooh.kz/api/v1/creatives/lookup", 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))
}