Dokumentation för partner-API:et

API med data om politiska reklammeddelanden för medie- och utgivarpartner

API v1

Partnerbärartoken krävs

Följer GDPR

Bas-URL

https://polads.eu/api/v1

Alla slutpunkter kräver autentisering med partnerbärartoken

Anropsbegränsning

Alla partnerslutpunkter delar samma anropsgräns per bärartoken

GET /advertisement-full/{PAID}

1 000 förfrågningar per minut

GET /advertisement/{PAID}

1 000 förfrågningar per minut

Anropsgränsen tillämpas per partnertoken för alla slutpunkter

Åtkomstkrav

Vad ett partnertoken måste uppfylla innan någon slutpunkt svarar

Pro-abonnemang, kontrolleras vid varje förfrågan

Partner-API:et ingår i Pro-abonnemanget, både vid läsning och skrivning. Det finns inget separat API-tillägg att köpa. Abonnemanget kontrolleras vid varje enskild förfrågan i stället för att registreras när tokenet skapas, så ett utgånget abonnemang stoppar åtkomsten redan vid nästa anrop med 403 PRO_PLAN_REQUIRED, och en förnyelse återställer den lika omedelbart.

Åtkomstnivåer

Alla partnertokens kan läsa. För att rapportera engagemangsmått krävs dessutom åtkomstnivån metrics:write. Åtkomstnivåerna väljs när tokenet skapas och kan inte ändras efteråt: vill du ändra dem återkallar du tokenet och skapar ett nytt.

Endast partnertokens

Dessa slutpunkter avvisar ett SSP-token med 401, och SSP-slutpunkten avvisar ett partnertoken på samma sätt. De två typerna är separata inloggningsuppgifter, inte två behörighetsnivåer för samma uppgifter.

När en slutpunkt returnerar 404

En 404 bevisar inte att ett PA-ID är fel

GET /advertisement/{PAID} slår upp annonsen enligt samma synlighetsregel som det offentliga registret. En annons som ännu inte är bekräftad, som utgivaren ännu inte har godkänt, eller vars startdatum för publicering fortfarande ligger i framtiden, ger 404 här precis som i registret. Detsamma gäller SSP-slutpunkten.

Slutpunkten för den fullständiga posten fungerar medvetet annorlunda

GET /advertisement-full/{PAID} är begränsad till dina egna annonser och svarar därför även för en annons som ännu inte har nått sitt startdatum. Du är den utgivare som måste granska annonsen innan den publiceras, så att undanhålla den från dig skulle motverka syftet.

GET

/advertisement-full/{PAID}

Hämta fullständiga annonsdata inklusive ALLA GDPR-känsliga fält (kräver Bearer-token)

Begränsad till dina egna annonser. Ett PA-ID från en annan utgivare, en egenpublicerad annons utan utgivare och en identifierare som inte finns ger alla samma 404, och svaret skiljer inte mellan dem.

⚠️ Varning: GDPR-känsliga uppgifter

Den här slutpunkten returnerar ALLA fält, inklusive e-postadresser, telefonnummer och fullständiga adresser. Använd den bara om du har ett berättigat verksamhetsbehov och lämpliga personuppgiftsbiträdesavtal på plats.

Bearer-token

PA-ID

Exempelbegäran

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

Svaret innehåller (OFILTRERAT)

Annonsörsfält:

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

Kampanjfält:

name, totalValue, medium, isOngoing, startDate, endDate

Annonsörer och personuppgiftsansvariga:

Alla fält, inklusive e-postadresser, telefonnummer och fullständiga adresser

Rapportera engagemangsmått

PUT

/advertisement/{PAID}/metrics

Skicka antalet visningar och interaktioner efter publicering för dina egna annonser.

Den här slutpunkten kräver en nyckel med åtkomstnivån Läsning och skrivning. Partner-API:et ingår i Pro-abonnemanget.

Du kan bara rapportera mått för annonser som publicerats via ditt eget konto.

Annonsen tillhör en annan utgivare. Ingenting skrivs.

Exempelbegäran

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

Tillgängliga fält

Datafält som API:t returnerar, med deras datatyper

Grundläggande information

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Efterlevnad och finansiering

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Inriktning

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridisk information och metadata

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

anger ett valfritt fält som kan vara null eller tomt

Kodexempel

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

Felsvar

Varje fel returnerar ett JSON-innehåll med ett felmeddelande, och varje svar innehåller huvudet X-API-Version. En maskinläsbar kod följer med avslagen för ogiltigt token och för abonnemang, liksom med metrics-slutpunktens egna valideringsfel. Ett saknat Authorization-huvud, ett 404- eller 429-svar från en lässlutpunkt och alla interna serverfel innehåller bara meddelandet.

401 INVALID_TOKEN

Inget aktivt token matchar Bearer-uppgifterna, eller så har tokenet återkallats. Ett saknat eller felaktigt Authorization-huvud besvaras också med 401, men bara metrics-slutpunkten märker svaret med den här koden. Ett SSP-token mot en partnerslutpunkt besvaras på samma sätt.

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 är giltigt men dess utgivare har inte Pro-abonnemanget. Detta kontrolleras före åtkomstnivån, så ett token med enbart läsbehörighet som tillhör en utgivare utan Pro rapporterar abonnemanget och inte åtkomstnivån.

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 är giltigt och har Pro, men saknar åtkomstnivån metrics:write som krävs för att rapportera mått.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Annonsen tillhör en annan utgivare. Ingenting skrivs.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Förfrågans innehåll är inte giltig JSON, eller så saknas de två värdena, är negativa eller är inte heltal. Svaret anger vad som gick fel.

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

Annonsen ligger utanför det område som engagemangsmått är definierade för. Bilaga II not 15 omfattar en onlineannons eller inbyggd annons som har använt inriktningsteknik eller annonsleveransteknik och som har börjat visas. Ingenting skrivs.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Ingen annons matchar det PA-ID:t, eller så är den inte synlig för dig ännu. Läs avsnittet ovan innan du utgår från att identifieraren är fel.

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 per token överskreds. Svaret innehåller X-RateLimit-Limit, X-RateLimit-Remaining och 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"
}

Versionshantering och utfasning

Detta är API-version v1, och varje svar anger det i huvudet X-API-Version. Ändringar som inte är bakåtkompatibla publiceras under en ny sökväg i stället för att den här ändras. En v1-slutpunkt stängs inte av utan ett Deprecation-huvud minst 90 dagar i förväg, enligt RFC 8594.

Maskinläsbar specifikation

Hela OpenAPI 3.1-dokumentet finns på /api/docs. Rikta Postman, Swagger UI eller en klientgenerator direkt dit i stället för att skriva av den här sidan.

https://polads.eu/api/docs

Integrerar du som säljplattform (SSP)? Läs dokumentationen för SSP-API:t

Dokumentation för partner-API:et

API med data om politiska reklammeddelanden för medie- och utgivarpartner

API v1

Partnerbärartoken krävs

Följer GDPR

Bas-URL

https://polads.eu/api/v1

Alla slutpunkter kräver autentisering med partnerbärartoken

Anropsbegränsning

Alla partnerslutpunkter delar samma anropsgräns per bärartoken

GET /advertisement-full/{PAID}

1 000 förfrågningar per minut

GET /advertisement/{PAID}

1 000 förfrågningar per minut

Anropsgränsen tillämpas per partnertoken för alla slutpunkter

Åtkomstkrav

Vad ett partnertoken måste uppfylla innan någon slutpunkt svarar

Pro-abonnemang, kontrolleras vid varje förfrågan

Åtkomstnivåer

Endast partnertokens

När en slutpunkt returnerar 404

En 404 bevisar inte att ett PA-ID är fel

Slutpunkten för den fullständiga posten fungerar medvetet annorlunda

GET

/advertisement-full/{PAID}

Hämta fullständiga annonsdata inklusive ALLA GDPR-känsliga fält (kräver Bearer-token)

⚠️ Varning: GDPR-känsliga uppgifter

Bearer-token

PA-ID

Exempelbegäran

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

Svaret innehåller (OFILTRERAT)

Annonsörsfält:

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

Kampanjfält:

name, totalValue, medium, isOngoing, startDate, endDate

Annonsörer och personuppgiftsansvariga:

Alla fält, inklusive e-postadresser, telefonnummer och fullständiga adresser

Rapportera engagemangsmått

PUT

/advertisement/{PAID}/metrics

Skicka antalet visningar och interaktioner efter publicering för dina egna annonser.

Den här slutpunkten kräver en nyckel med åtkomstnivån Läsning och skrivning. Partner-API:et ingår i Pro-abonnemanget.

Du kan bara rapportera mått för annonser som publicerats via ditt eget konto.

Annonsen tillhör en annan utgivare. Ingenting skrivs.

Exempelbegäran

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

Tillgängliga fält

Datafält som API:t returnerar, med deras datatyper

Grundläggande information

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Efterlevnad och finansiering

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Inriktning

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridisk information och metadata

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

anger ett valfritt fält som kan vara null eller tomt

Kodexempel

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

Felsvar

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

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 är giltigt och har Pro, men saknar åtkomstnivån metrics:write som krävs för att rapportera mått.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Annonsen tillhör en annan utgivare. Ingenting skrivs.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Förfrågans innehåll är inte giltig JSON, eller så saknas de två värdena, är negativa eller är inte heltal. Svaret anger vad som gick fel.

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 annons matchar det PA-ID:t, eller så är den inte synlig för dig ännu. Läs avsnittet ovan innan du utgår från att identifieraren är fel.

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 per token överskreds. Svaret innehåller X-RateLimit-Limit, X-RateLimit-Remaining och 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"
}

Versionshantering och utfasning

Maskinläsbar specifikation

Hela OpenAPI 3.1-dokumentet finns på /api/docs. Rikta Postman, Swagger UI eller en klientgenerator direkt dit i stället för att skriva av den här sidan.

https://polads.eu/api/docs

Integrerar du som säljplattform (SSP)? Läs dokumentationen för SSP-API:t