For developers and partners

Diretsa data model

Diretsa's data model: the main things the platform keeps, how they connect, and every controlled list with the standard it follows. It describes kinds of data, never anyone's records. Machine-readable version: api.diretsa.com/api/model (also at /model.json).

Version 2026-11-04

Standards we use

Standard	Version	Used for
Ad Context Protocol (AdCP)	3.1	Products, formats, pricing, media buys, accounts and the 20 media channels
OpenOOH Venue Taxonomy	1.2	Venue types of screens and billboards
IAB Tech Lab Content Taxonomy	3.1	Audience interests (tier 1)
IAB Tech Lab Ad Product Taxonomy	2.0	Sensitive ad categories
ISO 3166-1 and 3166-2		Country (ZA) and provinces (ZA-GP, ZA-WC ...)
ISO 4217		Currency (ZAR)
schema.org		Organization, Place and Offer in the data model

How it fits together

Each arrow means "has". Select a box to read about it.

Organisation
Search

Entities

Organisation

A business on Diretsa: an advertiser (buys media) or a publisher (sells it). People are members with roles.

Key: org_id

schema.org: Organization

AdCP: Account (for advertisers buying over AdCP)

Field	Type	Description
`kind`	enum	advertiser or publisher
`brand_domain`	domain	Advertisers: the brand's verified website; ads may only link there or to approved pages
`ad_categories`	list	Advertisers: sensitive categories the brand declaresList: ad_categories
`ad_policy`	object	Publishers: blocked categories and brands, whether each ad is reviewed, auto-accept of orders
`trust_level`	enum	Sets booking limits; grows with verified history

has many Site — A publisher owns sites
has many Campaign — An advertiser runs campaigns
has many Payout — A publisher is paid monthly

Site

A property a publisher sells: a website, newsletter, screen network, radio station, publication or any of the 20 channels. Verified before it can sell.

Key: site_id

schema.org: WebSite (web), Periodical (newsletter, print), Organization (networks)

AdCP: Property (in adagents.json and publisher_properties)

Field	Type	Description
`domain`	domain	The site or network domain
`channel`	enum	The media channelList: channels Ad Context Protocol (AdCP)
`verified`	boolean	Ownership proven (meta tag, DNS or file)
`audience`	AudienceProfile	The publisher's description of its audience, dated

has many Placement — Spaces for sale on the site
has one AudienceProfile — Who the site reaches

AudienceProfile

Who a site reaches, in the publisher's words and dated; Diretsa adds counted impressions for websites and newsletters.

Key: site_id

Field	Type	Description
`regions`	list	"national" or provincesList: provinces ISO 3166-1 and 3166-2
`languages`	list	Languages of the audienceList: languages
`age_groups`	list	Age bandsList: age_groups
`income_groups`	list	Income bandsList: income_groups
`interests`	list	InterestsList: interests IAB Tech Lab Content Taxonomy
`monthly_reach`	integer	People reached a month (publisher figure)

belongs to Site — Describes one site

Placement

One space for sale: an ad size on a website, a slot in a newsletter, a screen or set of screens, a radio spot. Sold to buyers as an AdCP product.

Key: product_id

schema.org: Offer

AdCP: Product

Field	Type	Description
`pricing_model`	enum	How it is pricedList: pricing_models Ad Context Protocol (AdCP)
`price`	money (ZAR)	Price under the pricing modelISO 4217
`min_spend`	money (ZAR)	Smallest booking
`format`	object	Size or material it takes (image, video, audio, document, text, brief)Ad Context Protocol (AdCP)
`proof_level`	enum	How strongly delivery can be checkedList: proof_levels
`listed`	boolean	On sale

belongs to Site — On one site
has one ScreenLocation — Screens and billboards: where it is
has many Package — Booked in packages

ScreenLocation

Where a screen or billboard placement is, and what kind of venue.

Key: product_id

schema.org: Place

Field	Type	Description
`lat, lng`	coordinates	WGS84
`city, province`	text	Province from the nineList: provinces ISO 3166-1 and 3166-2
`venue_type`	enum	Kind of venueList: venue_types OpenOOH Venue Taxonomy
`screen_ids`	list	The network's own ids for each physical screen
`impressions_per_play`	number	The network's estimate of people who see one play

belongs to Placement — Locates one placement

Campaign

An advertiser's plan: the brief, budget ceiling, dates, what it wants, and its artwork slots.

Key: campaign_id

Field	Type	Description
`brief`	text	Audience, goal, anything to avoid, in words
`objective`	enum	What the campaign is forList: objectives
`target_audience`	object	Languages, age groups, income groups, interests: the same vocabularies as AudienceProfileIAB Tech Lab Content Taxonomy
`regions`	list	Provinces (empty: all of South Africa)List: provinces ISO 3166-1 and 3166-2
`categories`	list	Sensitive categories declaredList: ad_categories IAB Tech Lab Ad Product Taxonomy
`max_total_budget`	money (ZAR)	Ceiling across all its bookings

belongs to Organisation — Of one advertiser
has many Creative — Artwork slots
has many MediaBuy — Bookings made for it, after a draft is approved

Creative

Approved material for a slot: an image, video, audio, document, text or brief, with its click-through on the brand's domain.

Key: creative_id

AdCP: Creative

Field	Type	Description
`kind`	enum	image, video, audio, document, text or brief
`click_url`	url	On the brand's domain or an approved destination

many to many Package — Assigned to packages

MediaBuy

A booking: made in the console from an approved draft, or by an AI agent over AdCP. Prepaid or within a credit line.

Key: media_buy_id

AdCP: Media buy

Field	Type	Description
`start, end`	datetime	Flight, Africa/Johannesburg
`total_budget`	money (ZAR)	Reserved when booked
`status`	enum	pending_creatives, pending_start, active, paused, completed, rejected, canceledAd Context Protocol (AdCP)

has many Package — One package per placement booked
belongs to Organisation — Paid by one advertiser

Package

One placement within a booking, with its budget, price and creatives.

Key: package_id

AdCP: Package

Field	Type	Description
`budget`	money (ZAR)	Spend on this placement
`pricing_option_id`	id	Which price appliesAd Context Protocol (AdCP)

belongs to Placement — Of one placement
has one Order — Channels the publisher runs: the order they accept and report on
has many DeliveryReport — Counted delivery

Order

A package a publisher runs themselves (screens, radio, print ...): accepted or declined, then reported with proof.

Key: order_id

Field	Type	Description
`status`	enum	awaiting_material, new, accepted, declined, canceled
`proof`	list	Play logs, tear sheets, photos, platform reportsList: proof_levels

belongs to Package — Runs one package

DeliveryReport

What ran: impressions and clicks counted by Diretsa's ad server, or units (plays, spots, screen-days) reported with proof. Earnings are settled after a dispute window.

Key: package_id + date

Field	Type	Description
`impressions, clicks, units`	integer	By day
`spend`	money (ZAR)	At the booked price

belongs to Package — For one package

Search

What an advertiser or its AI agent asked Diretsa for (brief and filters), kept 180 days, seen only by that advertiser and, in aggregate, by Diretsa.

Key: search_id

Field	Type	Description
`brief`	text	Private to the advertiser
`read`	object	Provinces, languages and interests Diretsa read from itIAB Tech Lab Content Taxonomy
`matched`	integer	Placements that fit

belongs to Organisation — Of one advertiser

Payout

A publisher's monthly payment of settled earnings, by Paystack transfer.

Key: payout_id

Field	Type	Description
`amount`	money (ZAR)	Earnings after the dispute window, 70% of media revenue by default

belongs to Organisation — To one publisher

Lists (vocabularies)

channels · 20 values · Ad Context Protocol (AdCP)

Standard: Ad Context Protocol (AdCP) 3.1

id	label	proof_level
display	Website display	measured
olv	Online video	machine
social	Social media	machine
search	Search	machine
ctv	Connected TV / streaming TV	machine
linear_tv	Broadcast TV	self_reported
radio	Radio	self_reported
streaming_audio	Streaming audio	machine
podcast	Podcast	machine
dooh	Digital screens (DOOH)	machine
ooh	Billboards and outdoor	self_reported
print	Print (newspapers and magazines)	self_reported
cinema	Cinema	self_reported
email	Newsletter / email	measured
gaming	Gaming	machine
retail_media	Retail media	machine
influencer	Creators and influencers	self_reported
affiliate	Affiliate	self_reported
product_placement	Product placement	self_reported
sponsored_intelligence	Sponsored AI answers	machine

pricing_models · 10 values · Ad Context Protocol (AdCP)

Standard: Ad Context Protocol (AdCP) 3.1

id	label
cpm	per 1 000 impressions
vcpm	per 1 000 viewable impressions
cpc	per click
cpcv	per completed view
cpv	per view
cpp	per rating point
cpa	per sale or sign-up
revenue_share	% of sales revenue
flat_rate	per unit
time	per period

proof_levels · 3 values

id	label
measured	Verified by Diretsa
machine	Publisher's system report
self_reported	Publisher's own report

venue_types · 23 values · OpenOOH Venue Taxonomy

Standard: OpenOOH Venue Taxonomy 1.2

Accepts: Any OpenOOH 1.2 enumeration id or string value at any level; it is turned into the nearest Diretsa venue type.

Diretsa id	Label	OpenOOH code	OpenOOH id
mall	Mall	retail.mall	205
roadside	Roadside	outdoor.billboard	301
airport	Airport	transit.airports	101
taxi_rank	Taxi rank	transit.bus.terminal	10202
in_taxi	Inside taxis	transit.taxi_rideshare_tv	103
train_station	Train station	transit.train.station	10604
bus_station	Bus station	transit.bus.terminal	10202
petrol_station	Petrol station	retail.gas_stations	201
retail	Shop	retail.other	216
grocery	Grocery store	retail.grocery	203
pharmacy	Pharmacy	retail.pharmacies	207
gym	Gym	health_beauty.gym	401
salon	Salon	health_beauty.salon	402
clinic	Clinic or doctor's rooms	point_care.doctor_office	501
hospital	Hospital	point_care.hospital	504
office	Office building	office_building.office_building	701
school	School	education.schools	601
campus	College or university	education.college	602
bar	Bar or tavern	entertainment.bars	804
restaurant	Restaurant	entertainment.casual_dining	805
hospitality	Hotel	entertainment.hotels	807
stadium	Stadium or sports venue	entertainment.sports	803
other	Other

interests · 35 values · IAB Tech Lab Content Taxonomy

Standard: IAB Tech Lab Content Taxonomy 3.1

Name	IAB id
Attractions	150
Automotive	1
Books and Literature	42
Business and Finance	52
Careers	123
Communication	80DV8O
Crime	380
Disasters	381
Education	132
Entertainment	JLBCU7
Events	8VZQHL
Family and Relationships	186
Fine Art	201
Food & Drink	210
Healthy Living	223
Hobbies & Interests	239
Holidays	1KXCLD
Home & Garden	274
Law	383
Medical Health	286
Personal Celebrations & Life Events	163
Personal Finance	391
Pets	422
Politics	386
Pop Culture	432
Real Estate	441
Religion & Spirituality	453
Science	464
Shopping	473
Sports	483
Style & Fashion	552
Technology & Computing	596
Travel	653
Video Gaming	680
War and Conflicts	389

ad_categories · 9 values · IAB Tech Lab Ad Product Taxonomy

Standard: IAB Tech Lab Ad Product Taxonomy 2.0

Accepts: Diretsa ids, or IAB Ad Product Taxonomy 2.0 ids ("1361" or "iab:1361").

Diretsa id	Label	IAB Ad Product ids	IAB names
alcohol	Alcohol	1002	Alcohol
gambling	Gambling and betting	1361	Gambling
tobacco	Tobacco and vaping	1544	Tobacco
dating	Dating	1259	Dating
crypto	Crypto and trading	1448	Non-Fiat Currency
loans	Loans and debt	1349, 1338	Finance and Insurance / Payday and Emergency Loans, Finance and Insurance / Credit and Debt Repair/Credit Reporting
weight_loss	Weight loss and supplements	1291, 1255	Dieting and Weightloss, Consumer Packaged Goods / Vitamins and Supplements / Weightloss Supplements
politics	Political	1474	Politics
religion	Religious	1487	Religion and Spirituality

provinces · 9 values · ISO 3166-1 and 3166-2

Standard: ISO 3166-1 and 3166-2

Province	ISO 3166-2
Eastern Cape	ZA-EC
Free State	ZA-FS
Gauteng	ZA-GP
KwaZulu-Natal	ZA-KZN
Limpopo	ZA-LP
Mpumalanga	ZA-MP
North West	ZA-NW
Northern Cape	ZA-NC
Western Cape	ZA-WC

languages · 12 values

South Africa's official languages

id	label
English	English
Afrikaans	Afrikaans
isiZulu	isiZulu
isiXhosa	isiXhosa
Sepedi	Sepedi
Setswana	Setswana
Sesotho	Sesotho
Xitsonga	Xitsonga
siSwati	siSwati
Tshivenda	Tshivenda
isiNdebele	isiNdebele
South African Sign Language	South African Sign Language

age_groups · 6 values

id	label
under_18	under 18
18_24	18–24
25_34	25–34
35_49	35–49
50_64	50–64
65_plus	65+

income_groups · 5 values

Plain bands; the licensed SAARF/MAPS segments are not used

id	label
lower	lower
lower_middle	lower middle
middle	middle
upper_middle	upper middle
upper	upper

objectives · 4 values

id	label
awareness	Get known (reach and impressions)
visits	Website visits (clicks)
signups	Sign-ups or leads
sales	Sales

currencies · 1 values · ISO 4217

Standard: ISO 4217

id	label
ZAR	South African rand

countries · 1 values · ISO 3166-1 and 3166-2

Standard: ISO 3166-1 and 3166-2

id	label
ZA	South Africa