Documentation de l’API partenaire
API de données sur les annonces publicitaires à caractère politique pour les partenaires médias et éditeurs
https://polads.eu/api/v1Tous les points de terminaison nécessitent une authentification par jeton Bearer partenaire
GET /advertisement-full/{PAID}
1 000 requêtes par minute
GET /advertisement/{PAID}
1 000 requêtes par minute
La limite de débit est appliquée par jeton partenaire sur l’ensemble des points de terminaison
Formule Pro, revérifiée à chaque requête
L’API partenaire fait partie de la formule Pro, en lecture comme en écriture. Il n’existe pas de module API à acheter séparément. La formule est vérifiée à chaque requête plutôt qu’enregistrée à la création du jeton, de sorte qu’un abonnement expiré interrompt l’accès dès l’appel suivant avec 403 PRO_PLAN_REQUIRED, et qu’un renouvellement le rétablit tout aussi immédiatement.
Portées
Tout jeton partenaire peut lire. La déclaration des chiffres d’engagement exige en plus la portée metrics:write. Les portées sont choisies à la création du jeton et ne peuvent plus être modifiées ensuite : pour les changer, révoquez le jeton et créez-en un nouveau.
Jetons partenaires uniquement
Ces points de terminaison rejettent un jeton SSP avec une erreur 401, et le point de terminaison SSP rejette un jeton partenaire de la même façon. Les deux niveaux sont des identifiants distincts, et non deux niveaux d’autorisation d’un même identifiant.
GET /advertisement/{PAID} retrouve l’annonce selon la même règle de visibilité que le registre public. Une annonce qui n’est pas encore confirmée, que son éditeur n’a pas encore validée ou dont la date de début de publication est encore à venir renvoie 404 ici, exactement comme dans le registre. Il en va de même pour le point de terminaison SSP.
Le point de terminaison de l’enregistrement complet est volontairement différent
GET /advertisement-full/{PAID} est limité à vos propres annonces et répond donc aussi pour une annonce qui n’a pas encore atteint sa date de début. Vous êtes l’éditeur qui doit examiner cette annonce avant sa diffusion : vous la refuser irait à l’encontre du but recherché.
/advertisement-full/{PAID}Limité à vos propres annonces. Le PA-ID d’un autre éditeur, une annonce auto-publiée sans éditeur et un identifiant inexistant renvoient tous le même 404, et la réponse ne les distingue pas.
⚠️ Avertissement : données sensibles au regard du RGPD
Ce point de terminaison renvoie TOUS les champs, y compris les e-mails, les numéros de téléphone et les adresses complètes. Utilisez-le uniquement si vous avez un besoin professionnel légitime et si des accords de traitement des données appropriés sont en place.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Champs de l’annonceur :
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Champs de la campagne :
name, totalValue, medium, isOngoing, startDate, endDate
Annonceurs et responsables du traitement :
Tous les champs, y compris les e-mails, les téléphones et les adresses complètes
/advertisement/{PAID}/metricsCe point de terminaison nécessite une clé dotée du niveau d’accès Lecture et écriture. L’API partenaire est incluse dans la formule Pro.
Vous ne pouvez déclarer des mesures que pour les annonces publiées depuis votre propre compte.
L’annonce appartient à un autre éditeur. Rien n’est écrit.
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}'Informations de base
Conformité et financement
Ciblage
Informations juridiques et métadonnées
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Aucun jeton actif ne correspond au justificatif Bearer, ou le jeton a été révoqué. Un en-tête Authorization absent ou mal formé renvoie aussi une réponse 401, mais seul le point de terminaison metrics lui associe ce code. Un jeton SSP utilisé sur un point de terminaison partenaire reçoit la même réponse.
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
Le jeton est valide, mais son éditeur n’a pas souscrit la formule Pro. Cette vérification précède celle de la portée : un jeton en lecture seule appartenant à un éditeur sans formule Pro signale donc la formule et non la portée.
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
Le jeton est valide et relève de la formule Pro, mais il ne dispose pas de la portée metrics:write nécessaire pour déclarer des chiffres d’engagement.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
L’annonce appartient à un autre éditeur. Rien n’est écrit.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}400 INVALID_METRICS
Le corps de la requête n’est pas du JSON valide, ou les deux compteurs sont absents, négatifs ou non entiers. La réponse indique ce qui a échoué.
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
L’annonce ne relève pas du champ pour lequel les chiffres d’engagement sont définis. La note 15 de l’annexe II vise une annonce en ligne ou native ayant eu recours à des techniques de ciblage ou de diffusion de la publicité et dont la diffusion a commencé. Rien n’est écrit.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
Aucune annonce ne correspond à ce PA-ID, ou elle ne vous est pas encore visible. Consultez la section ci-dessus avant de supposer que l’identifiant est erroné.
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
La limite par jeton a été dépassée. La réponse contient les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et 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"
}Il s’agit de la version v1 de l’API, et chaque réponse l’indique dans un en-tête X-API-Version. Les modifications incompatibles sont publiées sous un nouveau chemin, sans modifier celui-ci. Un point de terminaison v1 ne sera pas désactivé sans un en-tête Deprecation envoyé au moins 90 jours à l’avance, conformément à la RFC 8594.
Spécification lisible par une machine
Le document OpenAPI 3.1 complet est disponible à l’adresse /api/docs. Configurez Postman, Swagger UI ou un générateur de client pour l’utiliser directement plutôt que de recopier cette page.
https://polads.eu/api/docs