SSP API Documentation
Supply-side platform API for programmatic advertising platforms
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10,000 requests per minute
Rate limit enforced per SSP token
/online-advertisement/{PAID}📊 Compact Label Format
This endpoint returns a compact, EU-compliant transparency label suitable for display alongside online advertisements. Only works for advertisements with medium = "online".
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Display the label on your platform:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>Header Format
Authorization: Bearer YOUR_SSP_TOKENToken Format
64-character hexadecimal string (256-bit entropy)
Token Management
SSP tokens are managed by system administrators only. Contact your administrator to obtain a token.
No subscription plan applies
An SSP token is issued to an integrator rather than to a publisher, so it carries no publisher account and there is no plan to check. Unlike the partner API, nothing here depends on a subscription. A partner token is rejected on this endpoint with 401, and an SSP token is rejected on the partner endpoints the same way.
When the endpoint returns 404
The notice is resolved through the same visibility rule as the public register. A notice that is not yet confirmed, that its publisher has not yet signed off, or whose publication start date is still in the future returns 404. A 404 is therefore not proof that a PA-ID is wrong.
The endpoint above returns the one-line label TEXT, for a label your own platform draws. The badge returns a rendered, interactive notice you place beside the advertisement as an iframe. Both describe the same transparency notice.
One URL per version
The demo's controls map onto these parameters one to one, so you can choose on the demo page and copy the URL you see.
# Corner badge, mark only
GET https://polads.eu/badge/{PA-ID}
# Corner badge showing its wording
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Always-visible label strip
GET https://polads.eu/badge/{PA-ID}?layout=labelWhat each parameter does, and what leaving it out means
layout=label selects the strip. Leave it out for the corner badge. variant=labelled makes the closed badge show its wording. Leave it out for the mark alone. w and h declare the slot the badge sits in and choose how it degrades in a tight space. Leave them out and the badge assumes it has room, which is right for the standard formats.
hover=0 is for the demo, not for your page
It forces the no-hover layout so the demo can show the touch version on a desktop browser. The real badge tests the device for itself. Pin it and you send the wrong version to every visitor whose device disagrees.
The resize listener is required
The corner badge loads at 32 by 32 so it covers as little of the creative as it can, then asks the host page for room when it opens. Without the listener it cannot open at all. The label strip degrades more gently, and only clips at narrow widths.
Available only for a published notice
The badge is served once the notice is confirmed, signed off by the publisher and past its publication start date. An embargoed or unsigned PA-ID answers 404 by design, not by fault.
401 Unauthorized
{ "error": "Invalid or revoked SSP API token." }400 Bad Request
The notice was found, but its medium is not online. The response returns the actual medium value, for example print. A missing or unknown PA-ID returns 404 instead.
404 Not Found
{ "error": "Advertisement not found" }429 Rate Limit Exceeded
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2025-01-15T10:30:00.000Z"
}This is API version v1, and every response says so in an X-API-Version header. Breaking changes ship under a new path rather than changing this one. A v1 endpoint will not be switched off without a Deprecation header at least 90 days beforehand, following RFC 8594.
Machine-readable specification
The full OpenAPI 3.1 document is served at /api/docs. Point Postman, Swagger UI or a client generator straight at it rather than transcribing this page.
https://polads.eu/api/docs