Développeurs

Référence de l'API · v1

L'API Ads d'Echomi

REST sur HTTPS, JSON en entrée et en sortie. Ciblage contextuel uniquement, métriques agrégées et anonymes.

Bêta privée. Les clés API sont délivrées aux annonceurs de la bêta. Cette référence décrit l'API qu'ils utilisent.

Rejoindre la bêta annonceurs

Introduction

Toutes les ressources sont relatives à l'URL de base, en HTTPS uniquement. Les corps de requête et de réponse sont en JSON, les dates en ISO 8601.

https://api.echomi.app/v1

Clés & authentification

Chaque requête porte une clé API dans l'en-tête Authorization, au format Bearer. Les clés sont délivrées aux annonceurs de la bêta : une clé test (echo_test_…) et une clé live (echo_live_…). Gardez-les côté serveur, jamais dans une app ou une page web.

echo_test_…

Mode test : mêmes endpoints, même cycle de vie, rien n'est diffusé dans l'app.

echo_live_…

Mode live : les campagnes approuvées par la revue éditoriale sont diffusées.

GET /v1/me
curl https://api.echomi.app/v1/me \
  -H "Authorization: Bearer echo_test_3c91…"

Ciblage

Le ciblage est contextuel, et la liste des champs est fermée. Il n'existe aucun champ pour viser une personne, une liste de contacts, des choix ou des révélations : tout champ hors liste est refusé.

Champs acceptés · targeting

geostring[]
Codes pays ISO 3166-1 alpha-2. Le format moment (A) ajoute une zone et une fenêtre horaire.
min_agerequisinteger
18 minimum. Toute valeur inférieure est refusée.
langsstring[]
Langues de l'app (ISO 639-1).
interestsstring[]
Catégories d'intérêt que les membres ont choisies eux-mêmes (opt-in). Liste via GET /formats.
400 Bad Request
{
  "error": {
    "type": "invalid_request",
    "code": "targeting_field_not_allowed",
    "param": "targeting.custom_audience",
    "message": "Targeting is contextual only: geo, min_age, langs, interests."
  }
}

Compte

Vérifiez qu'une clé fonctionne et voyez à quel compte annonceur elle appartient.

GET/me

Vérifie la clé API et renvoie le compte annonceur associé, ses scopes et l'environnement de la clé (live ou test).

Requête
curl https://api.echomi.app/v1/me \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "account_id": "acc_graincoffee",
  "name": "Grain Coffee Co.",
  "country": "FR",
  "verified": true,
  "scopes": ["campaigns:read", "campaigns:write", "reporting:read"],
  "key_env": "live"
}

Campagnes

Une campagne choisit un format — moment (A), cosmetic (B) ou question (C) — puis passe par la revue éditoriale Echomi avant toute diffusion.

POST/campaigns

Crée une campagne en brouillon (status draft). Soumettez-la ensuite avec /campaigns/{id}/submit.

Corps de la requête

namerequisstring
Nom interne, jamais affiché dans l'app.
formatrequis"moment" | "cosmetic" | "question"
Format A, B ou C.
billingrequis"sponsorship" | "revshare" | "cpm" | "cpe"
Doit être autorisé pour le format (voir GET /formats).
budgetrequis{ amount, currency }
Montant en unités entières de la devise.
schedulerequis{ start, end }
Dates ISO 8601 (AAAA-MM-JJ).
targetingrequisobject
Contextuel uniquement : geo, min_age, langs, interests.
creativerequisobject | creative_id
Créative en ligne, ou l'id d'une créative existante du même format.
Requête
curl https://api.echomi.app/v1/campaigns \
  -H "Authorization: Bearer echo_test_3c91…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Grain Coffee · Morning Drop",
    "format": "question",
    "billing": "cpe",
    "budget": { "amount": 12000, "currency": "EUR" },
    "schedule": { "start": "2026-07-01", "end": "2026-07-14" },
    "targeting": {
      "geo": ["FR", "BE"],
      "min_age": 18,
      "langs": ["fr"],
      "interests": ["coffee", "food_drink"]
    },
    "creative": { "prompt": "Who deserves a coffee on you today?" }
  }'
Réponse · 201
{
  "id": "cmp_8K2D",
  "name": "Grain Coffee · Morning Drop",
  "format": "question",
  "billing": "cpe",
  "status": "draft",
  "budget": { "amount": 12000, "currency": "EUR", "spent": 0 },
  "schedule": { "start": "2026-07-01", "end": "2026-07-14" },
  "targeting": {
    "geo": ["FR", "BE"],
    "min_age": 18,
    "langs": ["fr"],
    "interests": ["coffee", "food_drink"]
  },
  "creative": { "prompt": "Who deserves a coffee on you today?" },
  "editorial_review": { "state": "not_submitted" },
  "created_at": "2026-06-08T10:24:00Z"
}

GET/campaigns

Liste les campagnes du compte, avec pagination par curseur et filtres.

Paramètres de requête

statusstring
draft, in_review, active, paused, rejected ou ended.
formatstring
moment, cosmetic ou question.
limitinteger
Entre 1 et 100.
cursorstring
La valeur next_cursor de la page précédente.
Requête
curl "https://api.echomi.app/v1/campaigns?status=active&limit=20" \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "object": "list",
  "data": [
    {
      "id": "cmp_8K2D",
      "name": "Grain Coffee · Morning Drop",
      "format": "question",
      "status": "active",
      "billing": "cpe"
    },
    {
      "id": "cmp_3HV1",
      "name": "Open-air festival · Saturday",
      "format": "moment",
      "status": "active",
      "billing": "sponsorship"
    }
  ],
  "has_more": true,
  "next_cursor": "cmp_5T9P"
}

GET/campaigns/{id}

Récupère une campagne, ciblage et état de revue inclus.

Requête
curl https://api.echomi.app/v1/campaigns/cmp_8K2D \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "id": "cmp_8K2D",
  "name": "Grain Coffee · Morning Drop",
  "format": "question",
  "billing": "cpe",
  "status": "active",
  "budget": { "amount": 12000, "currency": "EUR", "spent": 7430 },
  "schedule": { "start": "2026-07-01", "end": "2026-07-14" },
  "targeting": {
    "geo": ["FR", "BE"],
    "min_age": 18,
    "langs": ["fr"],
    "interests": ["coffee", "food_drink"]
  },
  "creative": { "prompt": "Who deserves a coffee on you today?" },
  "editorial_review": { "state": "approved", "reviewed_at": "2026-06-26T09:12:00Z" }
}

PATCH/campaigns/{id}

Modifie un brouillon, ou ajuste le budget et le planning d'une campagne. Modifier la créative relance la revue.

Requête
curl -X PATCH https://api.echomi.app/v1/campaigns/cmp_8K2D \
  -H "Authorization: Bearer echo_live_8f2a…" \
  -H "Content-Type: application/json" \
  -d '{ "budget": { "amount": 15000, "currency": "EUR" } }'
Réponse · 200
{
  "id": "cmp_8K2D",
  "status": "active",
  "budget": { "amount": 15000, "currency": "EUR", "spent": 7430 },
  "updated_at": "2026-07-03T14:08:00Z"
}

POST/campaigns/{id}/submit

Soumet un brouillon à la revue éditoriale Echomi : registre social, conformité 18+, marquage « Sponsorisé ».

Requête
curl -X POST https://api.echomi.app/v1/campaigns/cmp_8K2D/submit \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "id": "cmp_8K2D",
  "status": "in_review",
  "editorial_review": { "state": "pending", "submitted_at": "2026-06-08T10:30:00Z" }
}

POST/campaigns/{id}/pause

Met en pause une campagne active. La diffusion s'arrête, le budget restant est conservé.

Requête
curl -X POST https://api.echomi.app/v1/campaigns/cmp_8K2D/pause \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{ "id": "cmp_8K2D", "status": "paused", "paused_at": "2026-07-05T08:00:00Z" }

POST/campaigns/{id}/resume

Reprend une campagne en pause, dans les limites de sa fenêtre planifiée.

Requête
curl -X POST https://api.echomi.app/v1/campaigns/cmp_8K2D/resume \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{ "id": "cmp_8K2D", "status": "active", "resumed_at": "2026-07-06T08:00:00Z" }

Métriques

Toujours agrégées et anonymes : aucune identité, aucune réponse individuelle. Les champs dépendent du format — participants, réponses et portée (A), adoptions et vues d'animation (B), impressions, réponses et taux d'engagement (C).

GET/campaigns/{id}/metrics

Renvoie les métriques agrégées d'une campagne, ventilables par jour.

Paramètres de requête

granularity"total" | "day"
total par défaut.
Requête
curl "https://api.echomi.app/v1/campaigns/cmp_8K2D/metrics?granularity=day" \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "campaign_id": "cmp_8K2D",
  "format": "question",
  "aggregated": true,
  "totals": {
    "impressions": 1842500,
    "answers": 96400,
    "engagement_rate": 0.052
  },
  "daily": [
    { "date": "2026-07-01", "impressions": 132400, "answers": 6890 },
    { "date": "2026-07-02", "impressions": 145100, "answers": 7510 }
  ]
}

Formats

Les trois formats, leurs modèles de facturation, leurs métriques et leurs garde-fous — lisibles par machine.

GET/formats

Liste les formats (A/B/C), les modèles de facturation autorisés, les catégories d'intérêt et les garde-fous.

Requête
curl https://api.echomi.app/v1/formats \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "object": "list",
  "data": [
    {
      "key": "moment", "letter": "A",
      "billing": ["sponsorship"],
      "metrics": ["participants", "answers", "reach"]
    },
    {
      "key": "cosmetic", "letter": "B",
      "billing": ["sponsorship", "revshare"],
      "metrics": ["adoptions", "animation_views"]
    },
    {
      "key": "question", "letter": "C",
      "billing": ["cpm", "cpe"],
      "min_age": 18,
      "register": "social_only",
      "max_per_drop": 1,
      "metrics": ["impressions", "answers", "engagement_rate"]
    }
  ],
  "interests": ["coffee", "food_drink", "music", "festivals", "sport", "travel"]
}

Créatives

Vos contenus vivent dans les gabarits Echomi : question sociale (C), cosmétique (B) ou habillage de moment (A). Chaque créative passe par la revue éditoriale.

POST/creatives

Crée une créative réutilisable, rattachable à toute campagne du même format.

Requête
curl https://api.echomi.app/v1/creatives \
  -H "Authorization: Bearer echo_live_8f2a…" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "question",
    "template": "drop_social",
    "prompt": "Which song would you send to your whole group tonight?"
  }'
Réponse · 200
{
  "id": "cr_2F8a",
  "format": "question",
  "template": "drop_social",
  "prompt": "Which song would you send to your whole group tonight?",
  "editorial_review": { "state": "pending" },
  "created_at": "2026-06-08T10:20:00Z"
}

Reporting

Consolide les métriques de toutes vos campagnes sur une période. Toujours agrégé, toujours anonyme.

GET/reporting

Renvoie un rapport consolidé sur une période, ventilable par format.

Paramètres de requête

fromrequisdate
Début de période (AAAA-MM-JJ).
torequisdate
Fin de période, incluse.
group_by"format"
Ventile les totaux par format.
Requête
curl "https://api.echomi.app/v1/reporting?from=2026-07-01&to=2026-07-14&group_by=format" \
  -H "Authorization: Bearer echo_live_8f2a…"
Réponse · 200
{
  "from": "2026-07-01",
  "to": "2026-07-14",
  "aggregated": true,
  "currency": "EUR",
  "totals": { "spend": 11550, "impressions": 2822700, "engagements": 140500 },
  "by_format": [
    { "format": "question", "spend": 7430, "impressions": 1842500, "engagements": 96400 },
    { "format": "cosmetic", "spend": 4120, "impressions": 980200, "engagements": 44100 }
  ]
}

Webhooks

Recevez le cycle de vie de vos campagnes en HTTP POST signé : campaign.approved, campaign.rejected, campaign.activated, campaign.paused, campaign.ended. Chaque envoi porte un en-tête Echomi-Signature (HMAC-SHA256 du corps brut avec votre secret whsec_).

POST/webhooks

Enregistre une URL de réception et les événements souscrits. Le secret de signature n'est renvoyé qu'une fois.

Requête
curl https://api.echomi.app/v1/webhooks \
  -H "Authorization: Bearer echo_live_8f2a…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.graincoffee.example/echomi",
    "events": [
      "campaign.approved", "campaign.rejected",
      "campaign.activated", "campaign.paused", "campaign.ended"
    ]
  }'
Réponse · 200
{
  "id": "wh_71Cd",
  "url": "https://hooks.graincoffee.example/echomi",
  "events": [
    "campaign.approved", "campaign.rejected",
    "campaign.activated", "campaign.paused", "campaign.ended"
  ],
  "secret": "whsec_…",
  "status": "enabled"
}

EVENTcampaign.approved

Exemple de charge utile envoyée à votre URL quand une campagne est approuvée par la revue éditoriale.

Charge utile reçue
{
  "id": "evt_9aF2",
  "type": "campaign.approved",
  "created_at": "2026-06-26T09:12:00Z",
  "data": {
    "campaign_id": "cmp_8K2D",
    "status": "active",
    "editorial_review": { "state": "approved" }
  }
}

Erreurs

L'API utilise les codes HTTP standard. Le corps d'erreur contient un objet error avec type, code, param (si un champ est en cause) et un message lisible.

  • 400Bad RequestRequête invalide, ou ciblage hors liste (ex. une audience de personnes).
  • 401UnauthorizedClé API manquante ou invalide.
  • 403ForbiddenScope insuffisant pour cette opération.
  • 404Not FoundRessource introuvable.
  • 429Too Many RequestsLimite de débit dépassée — réessayez après Retry-After.
  • 500Server ErrorErreur côté Echomi. Réessayez avec un backoff exponentiel.

Limites de débit

Les limites sont fixées par compte pendant la bêta et communiquées avec vos clés. Chaque réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; au-delà, l'API renvoie 429 avec un en-tête Retry-After.

Pagination

Les endpoints de liste utilisent une pagination par curseur. Passez limit (max 100) et cursor ; la réponse contient has_more et next_cursor.

GET /v1/campaigns
curl "https://api.echomi.app/v1/campaigns?limit=20&cursor=cmp_5T9P" \
  -H "Authorization: Bearer echo_live_8f2a…"

Prêt à construire ?

Rejoignez la bêta annonceurs : nous revenons vers vous avec vos clés test et live.