Partner API-dokumentation

API til data om politiske annoncer for medie- og udgiverpartnere

API v1

Partner Bearer Token påkrævet

GDPR-kompatibel

Base URL

https://polads.eu/api/v1

Alle endpoints kræver partner Bearer token-autentificering

Ratebegrænsning

Alle partner-endpoints deler samme rate limit pr. Bearer token

GET /advertisement-full/{PAID}

1.000 forespørgsler pr. minut

GET /advertisement/{PAID}

1.000 forespørgsler pr. minut

Ratebegrænsningen håndhæves pr. partner-token på tværs af alle endpoints

Adgangskrav

Hvad et partnertoken skal have, før et endpoint svarer

Pro-abonnement, kontrolleret ved hver forespørgsel

Partner-API’et er en del af Pro-abonnementet, både ved læsning og skrivning. Der er ikke noget separat API-tilkøb. Abonnementet slås op ved hver eneste forespørgsel i stedet for at blive gemt, da tokenet blev oprettet, så et udløbet abonnement stopper adgangen ved næste kald med 403 PRO_PLAN_REQUIRED, og en fornyelse genåbner den lige så hurtigt.

Scopes

Alle partnertokens kan læse. Indberetning af engagementstal kræver derudover scopet metrics:write. Scopes vælges, når tokenet oprettes, og kan ikke ændres bagefter: vil du ændre dem, skal du tilbagekalde tokenet og oprette et nyt.

Kun partnertokens

Disse endpoints afviser et SSP-token med 401, og SSP-endpointet afviser et partnertoken på samme måde. De to typer er separate legitimationsoplysninger, ikke to rettighedsniveauer på én.

Hvornår et endpoint svarer 404

En 404 er ikke bevis for, at et PA-ID er forkert

GET /advertisement/{PAID} slår annoncen op efter samme synlighedsregel som det offentlige register. En annonce, der endnu ikke er bekræftet, som udgiveren endnu ikke har godkendt, eller hvis publiceringsdato ligger ude i fremtiden, svarer 404 her præcis som i registret. Det samme gælder SSP-endpointet.

Endpointet med den fulde post er bevidst anderledes

GET /advertisement-full/{PAID} er afgrænset til dine egne annoncer, så det svarer også for en annonce, der endnu ikke har nået sin startdato. Du er den udgiver, der skal gennemgå annoncen, før den kører, så det ville modarbejde formålet at holde den tilbage fra dig.

GET

/advertisement-full/{PAID}

Hent komplette annonce-data inkl. ALLE GDPR-følsomme felter (kræver Bearer token)

Afgrænset til dine egne annoncer. Et PA-ID fra en anden udgiver, en selvpubliceret annonce uden udgiver og en identifikator, der ikke findes, svarer alle det samme 404, og svaret skelner ikke mellem dem.

⚠️ Advarsel om GDPR-følsomme data

Dette endpoint returnerer ALLE felter inklusive e-mails, telefonnumre og fulde adresser. Brug kun dette endpoint, hvis du har et legitimt forretningsbehov og korrekte databehandleraftaler på plads.

Bearer-token

PA-ID

Eksempel på request

curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response inkluderer (UFILTRERET)

Annoncørfelter:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Kampagnefelter:

name, totalValue, medium, isOngoing, startDate, endDate

Annoncører & kontrollerende enheder:

Alle felter inkl. emails, telefonnumre og fulde adresser

Indberet engagementsmålinger

PUT

/advertisement/{PAID}/metrics

Send tal for visninger og engagementer efter offentliggørelse for dine egne annoncer.

Dette endpoint kræver en nøgle med adgangsniveauet Læsning og skrivning. Partner-API'et er inkluderet i Pro-abonnementet.

Du kan kun indberette målinger for annoncer, der er offentliggjort via din egen konto.

Annoncen tilhører en anden udgiver. Der skrives ingenting.

Eksempel på request

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

Tilgængelige felter

Datafelter som API'et returnerer med deres typer

Grundlæggende information

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Compliance & finansiering

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Målretning

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridisk & metadata

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

angiver et valgfrit felt, som kan være null eller tomt

Kodeeksempler

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Fejlrespons

Hver fejl returnerer en JSON-body med en fejlbesked, og hvert svar indeholder et X-API-Version-header. En maskinlæsbar kode følger med afvisninger af ugyldigt token og af abonnement samt med metrics-endpointets egne valideringsfejl. Et manglende Authorization-header, en 404 eller 429 fra et læse-endpoint og enhver intern serverfejl indeholder kun beskeden.

401 INVALID_TOKEN

Intet aktivt token matcher Bearer-legitimationen, eller tokenet er tilbagekaldt. Et manglende eller ugyldigt Authorization-header svarer også 401, men kun metrics-endpointet mærker det med denne kode. Et SSP-token på et partner-endpoint svarer på samme måde.

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

Tokenet er gyldigt, og udgiveren er ikke på Pro-abonnementet. Dette kontrolleres før scopet, så et token med læseadgang hos en udgiver uden Pro melder om abonnementet frem for om scopet.

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

Tokenet er gyldigt og har Pro, men mangler scopet metrics:write, som er nødvendigt for at indberette tal.

PUT /advertisement/{PAID}/metrics

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

403 FORBIDDEN

Annoncen tilhører en anden udgiver. Der skrives ingenting.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

400 INVALID_METRICS

Forespørgselsindholdet er ikke gyldig JSON, eller de to tal mangler, er negative eller ikke hele tal. Svaret oplyser, hvad der fejlede.

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

Annoncen falder uden for det område, engagementstal er defineret for. Annex II note 15 dækker en online- eller native-annonce, der har brugt målretning eller leveringsteknikker, og som er begyndt at køre. Der skrives ingenting.

PUT /advertisement/{PAID}/metrics

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

404 NOT_FOUND

Ingen annonce matcher det PA-ID, eller den er endnu ikke synlig for dig. Læs afsnittet ovenfor, før du går ud fra, at identifikatoren er forkert.

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

Grænsen pr. token blev overskredet. Svaret indeholder X-RateLimit-Limit, X-RateLimit-Remaining og 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"
}

Versionering og udfasning

Dette er API-version v1, og hvert svar oplyser det i et X-API-Version-header. Brydende ændringer udgives på en ny sti frem for at ændre denne. Et v1-endpoint lukkes ikke ned uden et Deprecation-header mindst 90 dage før, jf. RFC 8594.

Maskinlæsbar specifikation

Det fulde OpenAPI 3.1-dokument findes på /api/docs. Peg Postman, Swagger UI eller en klientgenerator direkte derhen frem for at skrive denne side af.

https://polads.eu/api/docs

Integrerer du som supply-side-platform? Læs SSP-API-dokumentationen

Partner API-dokumentation

API til data om politiske annoncer for medie- og udgiverpartnere

API v1

Partner Bearer Token påkrævet

GDPR-kompatibel

Base URL

https://polads.eu/api/v1

Alle endpoints kræver partner Bearer token-autentificering

Ratebegrænsning

Alle partner-endpoints deler samme rate limit pr. Bearer token

GET /advertisement-full/{PAID}

1.000 forespørgsler pr. minut

GET /advertisement/{PAID}

1.000 forespørgsler pr. minut

Ratebegrænsningen håndhæves pr. partner-token på tværs af alle endpoints

Adgangskrav

Hvad et partnertoken skal have, før et endpoint svarer

Pro-abonnement, kontrolleret ved hver forespørgsel

Scopes

Kun partnertokens

Disse endpoints afviser et SSP-token med 401, og SSP-endpointet afviser et partnertoken på samme måde. De to typer er separate legitimationsoplysninger, ikke to rettighedsniveauer på én.

Hvornår et endpoint svarer 404

En 404 er ikke bevis for, at et PA-ID er forkert

Endpointet med den fulde post er bevidst anderledes

GET

/advertisement-full/{PAID}

Hent komplette annonce-data inkl. ALLE GDPR-følsomme felter (kræver Bearer token)

⚠️ Advarsel om GDPR-følsomme data

Dette endpoint returnerer ALLE felter inklusive e-mails, telefonnumre og fulde adresser. Brug kun dette endpoint, hvis du har et legitimt forretningsbehov og korrekte databehandleraftaler på plads.

Bearer-token

PA-ID

Eksempel på request

curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response inkluderer (UFILTRERET)

Annoncørfelter:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Kampagnefelter:

name, totalValue, medium, isOngoing, startDate, endDate

Annoncører & kontrollerende enheder:

Alle felter inkl. emails, telefonnumre og fulde adresser

Indberet engagementsmålinger

PUT

/advertisement/{PAID}/metrics

Send tal for visninger og engagementer efter offentliggørelse for dine egne annoncer.

Dette endpoint kræver en nøgle med adgangsniveauet Læsning og skrivning. Partner-API'et er inkluderet i Pro-abonnementet.

Du kan kun indberette målinger for annoncer, der er offentliggjort via din egen konto.

Annoncen tilhører en anden udgiver. Der skrives ingenting.

Eksempel på request

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

Tilgængelige felter

Datafelter som API'et returnerer med deres typer

Grundlæggende information

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Compliance & finansiering

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Målretning

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridisk & metadata

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

angiver et valgfrit felt, som kan være null eller tomt

Kodeeksempler

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Fejlrespons

401 INVALID_TOKEN

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

Tokenet er gyldigt, og udgiveren er ikke på Pro-abonnementet. Dette kontrolleres før scopet, så et token med læseadgang hos en udgiver uden Pro melder om abonnementet frem for om scopet.

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

Tokenet er gyldigt og har Pro, men mangler scopet metrics:write, som er nødvendigt for at indberette tal.

PUT /advertisement/{PAID}/metrics

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

403 FORBIDDEN

Annoncen tilhører en anden udgiver. Der skrives ingenting.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

400 INVALID_METRICS

Forespørgselsindholdet er ikke gyldig JSON, eller de to tal mangler, er negative eller ikke hele tal. Svaret oplyser, hvad der fejlede.

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

PUT /advertisement/{PAID}/metrics

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

404 NOT_FOUND

Ingen annonce matcher det PA-ID, eller den er endnu ikke synlig for dig. Læs afsnittet ovenfor, før du går ud fra, at identifikatoren er forkert.

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

Grænsen pr. token blev overskredet. Svaret indeholder X-RateLimit-Limit, X-RateLimit-Remaining og 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"
}

Versionering og udfasning

Maskinlæsbar specifikation

Det fulde OpenAPI 3.1-dokument findes på /api/docs. Peg Postman, Swagger UI eller en klientgenerator direkte derhen frem for at skrive denne side af.

https://polads.eu/api/docs

Integrerer du som supply-side-platform? Læs SSP-API-dokumentationen