Partner-API-Dokumentation
API für Daten zu politischer Werbung für Medien- und Herausgeberpartner
https://polads.eu/api/v1Alle Endpunkte erfordern eine Partner-Bearer-Token-Authentifizierung
GET /advertisement-full/{PAID}
1.000 Anfragen pro Minute
GET /advertisement/{PAID}
1.000 Anfragen pro Minute
Das Ratenlimit wird pro Partner-Token auf allen Endpunkten durchgesetzt
Pro-Tarif, bei jeder Anfrage erneut geprüft
Die Partner-API ist Teil des Pro-Tarifs, beim Lesen ebenso wie beim Schreiben. Ein separates API-Zusatzpaket gibt es nicht. Der Tarif wird bei jeder einzelnen Anfrage gelesen und nicht bei der Token-Erstellung gespeichert, daher beendet ein abgelaufenes Abonnement den Zugriff beim nächsten Aufruf mit 403 PRO_PLAN_REQUIRED, und eine Verlängerung stellt ihn ebenso unmittelbar wieder her.
Scopes
Jedes Partner-Token darf lesen. Für das Melden von Interaktionszahlen ist zusätzlich der Scope metrics:write nötig. Scopes werden bei der Erstellung des Tokens festgelegt und lassen sich danach nicht mehr ändern: Um sie zu ändern, widerrufen Sie das Token und erstellen ein neues.
Nur Partner-Tokens
Diese Endpunkte weisen ein SSP-Token mit 401 ab, und der SSP-Endpunkt weist ein Partner-Token genauso ab. Die beiden Arten sind getrennte Zugangsdaten, nicht zwei Berechtigungsstufen derselben.
GET /advertisement/{PAID} löst die Anzeige über dieselbe Sichtbarkeitsregel auf wie das öffentliche Register. Eine Anzeige, die noch nicht bestätigt ist, die der Herausgeber noch nicht freigegeben hat oder deren Veröffentlichungsbeginn noch in der Zukunft liegt, ergibt hier genau wie im Register 404. Für den SSP-Endpunkt gilt dasselbe.
Der Endpunkt mit dem vollständigen Datensatz ist bewusst anders
GET /advertisement-full/{PAID} ist auf Ihre eigenen Anzeigen beschränkt und antwortet deshalb auch für eine Anzeige, deren Startdatum noch nicht erreicht ist. Sie sind der Herausgeber, der diese Anzeige vor der Schaltung prüfen muss, sie Ihnen vorzuenthalten würde den Zweck verfehlen.
/advertisement-full/{PAID}Auf Ihre eigenen Anzeigen beschränkt. Die PA-ID eines anderen Herausgebers, eine selbst veröffentlichte Anzeige ohne Herausgeber und eine nicht existierende Kennung ergeben alle dasselbe 404, und die Antwort unterscheidet sie nicht.
⚠️ Warnung vor sensiblen Daten gemäß DSGVO
Dieser Endpunkt gibt ALLE Felder zurück, einschließlich E-Mails, Telefonnummern und vollständige Adressen. Verwenden Sie diesen Endpunkt nur, wenn Sie einen legitimen Geschäftsbedarf haben und ordnungsgemäße Datenverarbeitungsvereinbarungen vorliegen.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Werbetreibendenfelder:
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Kampagnenfelder:
name, totalValue, medium, isOngoing, startDate, endDate
Werbetreibende und kontrollierende Einrichtungen:
Alle Felder, einschließlich E-Mail-Adressen, Telefonnummern und vollständiger Anschriften
/advertisement/{PAID}/metricsDieser Endpunkt benötigt einen Schlüssel mit der Zugriffsebene Lesen und Schreiben. Die Partner-API ist im Pro-Tarif enthalten.
Sie können Kennzahlen nur für Anzeigen melden, die über Ihr eigenes Konto veröffentlicht wurden.
Die Anzeige gehört einem anderen Herausgeber. Es wird nichts geschrieben.
curl -X PUT "https://polads.eu/api/v1/advertisement/ABC12/metrics" \
-H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"viewsCount": 15000, "engagementsCount": 320}'Grundlegende Informationen
Compliance und Finanzierung
Targeting
Rechtliche Hinweise und Metadaten
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Kein aktives Token passt zum Bearer-Nachweis, oder das Token wurde widerrufen. Ein fehlender oder fehlerhafter Authorization-Header wird ebenfalls mit 401 beantwortet, aber nur der Metrics-Endpunkt kennzeichnet ihn mit diesem Code. Ein SSP-Token an einem Partner-Endpunkt wird genauso beantwortet.
GET /advertisement/{PAID}GET /advertisement-full/{PAID}{
"error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
"code": "INVALID_TOKEN"
}PUT /advertisement/{PAID}/metrics{
"error": "Invalid or revoked partner API token.",
"code": "INVALID_TOKEN"
}PUT /advertisement/{PAID}/metrics{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>",
"code": "INVALID_TOKEN"
}GET /advertisement/{PAID}GET /advertisement-full/{PAID}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}403 PRO_PLAN_REQUIRED
Das Token ist gültig und sein Herausgeber hat keinen Pro-Tarif. Das wird vor dem Scope geprüft, daher meldet ein nur lesendes Token eines Herausgebers ohne Pro den Tarif und nicht den Scope.
GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics{
"error": "The Pro plan is required to use the partner API.",
"code": "PRO_PLAN_REQUIRED"
}403 INSUFFICIENT_SCOPE
Das Token ist gültig und hat Pro, ihm fehlt aber der Scope metrics:write, der zum Melden von Zahlen nötig ist.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
Die Anzeige gehört einem anderen Herausgeber. Es wird nichts geschrieben.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}400 INVALID_METRICS
Der Anfragetext ist kein gültiges JSON, oder die beiden Zahlen fehlen, sind negativ oder keine ganzen Zahlen. Die Antwort nennt, was fehlgeschlagen ist.
PUT /advertisement/{PAID}/metrics{
"error": "Invalid engagement metrics",
"code": "INVALID_METRICS",
"issues": [
{
"path": "viewsCount",
"message": "Too small: expected number to be >=0"
}
]
}PUT /advertisement/{PAID}/metrics{
"error": "Invalid request body",
"code": "INVALID_METRICS"
}409 METRICS_NOT_APPLICABLE
Die Anzeige liegt außerhalb des Bereichs, für den Interaktionszahlen definiert sind. Annex II Anmerkung 15 erfasst eine Online- oder Native-Anzeige, die Targeting oder Auslieferungstechniken genutzt hat und bereits läuft. Es wird nichts geschrieben.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
Keine Anzeige passt zu dieser PA-ID, oder sie ist für Sie noch nicht sichtbar. Lesen Sie den Abschnitt oben, bevor Sie annehmen, die Kennung sei falsch.
PUT /advertisement/{PAID}/metrics{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}GET /advertisement/{PAID}{
"error": "Advertisement not found"
}GET /advertisement-full/{PAID}{
"error": "Advertisement not found or not yet confirmed"
}429 RATE_LIMITED
Das Limit pro Token wurde überschritten. Die Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.
PUT /advertisement/{PAID}/metrics{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}GET /advertisement/{PAID}GET /advertisement-full/{PAID}{
"error": "Rate limit exceeded",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Dies ist API-Version v1, und jede Antwort sagt das in einem X-API-Version-Header. Brechende Änderungen erscheinen unter einem neuen Pfad, statt diesen zu ändern. Ein v1-Endpunkt wird nicht abgeschaltet, ohne dass mindestens 90 Tage vorher ein Deprecation-Header gesetzt wird, gemäß RFC 8594.
Maschinenlesbare Spezifikation
Das vollständige OpenAPI-3.1-Dokument wird unter /api/docs ausgeliefert. Richten Sie Postman, Swagger UI oder einen Client-Generator direkt darauf, statt diese Seite abzuschreiben.
https://polads.eu/api/docs