Developers

API reference · v1

The Echomi Ads API

REST over HTTPS, JSON in and out. Contextual targeting only, aggregated and anonymous metrics.

Private beta. API keys are issued to beta advertisers. This reference describes the API they use.

Join the advertiser beta

Introduction

All resources are relative to the base URL, over HTTPS only. Request and response bodies are JSON, dates are ISO 8601.

https://api.echomi.app/v1

Keys & authentication

Every request carries an API key in the Authorization header, as a Bearer token. Keys are issued to beta advertisers: a test key (echo_test_…) and a live key (echo_live_…). Keep them server-side, never in an app or a web page.

echo_test_…

Test mode: same endpoints, same lifecycle, nothing is delivered in the app.

echo_live_…

Live mode: campaigns approved by editorial review are delivered.

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

Targeting

Targeting is contextual, and the list of fields is closed. There is no field to aim at a person, a contact list, picks or reveals: any field outside the list is rejected.

Accepted fields · targeting

geostring[]
ISO 3166-1 alpha-2 country codes. The moment format (A) adds a zone and a time window.
min_agerequiredinteger
18 at least. Any lower value is rejected.
langsstring[]
App languages (ISO 639-1).
interestsstring[]
Interest categories members chose themselves (opt-in). Listed by 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."
  }
}

Account

Check that a key works and see which advertiser account it belongs to.

GET/me

Verify the API key and return the associated advertiser account, its scopes and the key environment (live or test).

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

Campaigns

A campaign picks one format — moment (A), cosmetic (B) or question (C) — then goes through Echomi editorial review before any delivery.

POST/campaigns

Create a campaign as a draft (status draft). Then submit it with /campaigns/{id}/submit.

Request body

namerequiredstring
Internal name, never shown in the app.
formatrequired"moment" | "cosmetic" | "question"
Format A, B or C.
billingrequired"sponsorship" | "revshare" | "cpm" | "cpe"
Must be allowed for the format (see GET /formats).
budgetrequired{ amount, currency }
Amount in whole currency units.
schedulerequired{ start, end }
ISO 8601 dates (YYYY-MM-DD).
targetingrequiredobject
Contextual only: geo, min_age, langs, interests.
creativerequiredobject | creative_id
Inline creative, or the id of an existing creative of the same format.
Request
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?" }
  }'
Response · 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

List the account's campaigns, with cursor pagination and filters.

Query parameters

statusstring
draft, in_review, active, paused, rejected or ended.
formatstring
moment, cosmetic or question.
limitinteger
Between 1 and 100.
cursorstring
The next_cursor value from the previous page.
Request
curl "https://api.echomi.app/v1/campaigns?status=active&limit=20" \
  -H "Authorization: Bearer echo_live_8f2a…"
Response · 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}

Retrieve a single campaign, including targeting and review state.

Request
curl https://api.echomi.app/v1/campaigns/cmp_8K2D \
  -H "Authorization: Bearer echo_live_8f2a…"
Response · 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}

Edit a draft, or adjust a campaign's budget and schedule. Editing the creative re-triggers review.

Request
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" } }'
Response · 200
{
  "id": "cmp_8K2D",
  "status": "active",
  "budget": { "amount": 15000, "currency": "EUR", "spent": 7430 },
  "updated_at": "2026-07-03T14:08:00Z"
}

POST/campaigns/{id}/submit

Submit a draft to Echomi editorial review: social register, 18+ compliance, "Sponsored" marking.

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

POST/campaigns/{id}/pause

Pause an active campaign. Delivery stops, remaining budget is kept.

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

POST/campaigns/{id}/resume

Resume a paused campaign, within the bounds of its scheduled window.

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

Metrics

Always aggregated and anonymous: no identity, no individual answer. Fields depend on the format — participants, answers and reach (A), adoptions and animation views (B), impressions, answers and engagement rate (C).

GET/campaigns/{id}/metrics

Return a campaign's aggregated metrics, optionally split by day.

Query parameters

granularity"total" | "day"
Defaults to total.
Request
curl "https://api.echomi.app/v1/campaigns/cmp_8K2D/metrics?granularity=day" \
  -H "Authorization: Bearer echo_live_8f2a…"
Response · 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

The three formats, their billing models, metrics and guardrails — machine-readable.

GET/formats

List formats (A/B/C), allowed billing models, interest categories and guardrails.

Request
curl https://api.echomi.app/v1/formats \
  -H "Authorization: Bearer echo_live_8f2a…"
Response · 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"]
}

Creatives

Your content lives in Echomi templates: social question (C), cosmetic (B) or moment dressing (A). Every creative goes through editorial review.

POST/creatives

Create a reusable creative, attachable to any campaign of the same format.

Request
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?"
  }'
Response · 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

Consolidate metrics across all your campaigns over a period. Always aggregated, always anonymous.

GET/reporting

Return a consolidated report over a period, optionally split by format.

Query parameters

fromrequireddate
Period start (YYYY-MM-DD).
torequireddate
Period end, inclusive.
group_by"format"
Split totals by format.
Request
curl "https://api.echomi.app/v1/reporting?from=2026-07-01&to=2026-07-14&group_by=format" \
  -H "Authorization: Bearer echo_live_8f2a…"
Response · 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

Receive your campaigns' lifecycle as signed HTTP POSTs: campaign.approved, campaign.rejected, campaign.activated, campaign.paused, campaign.ended. Each delivery carries an Echomi-Signature header (HMAC-SHA256 of the raw body with your whsec_ secret).

POST/webhooks

Register a receiving URL and the subscribed events. The signing secret is only returned once.

Request
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"
    ]
  }'
Response · 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

Example payload sent to your URL when a campaign passes editorial review.

Delivered payload
{
  "id": "evt_9aF2",
  "type": "campaign.approved",
  "created_at": "2026-06-26T09:12:00Z",
  "data": {
    "campaign_id": "cmp_8K2D",
    "status": "active",
    "editorial_review": { "state": "approved" }
  }
}

Errors

The API uses standard HTTP codes. The error body holds an error object with type, code, param (when a field is at fault) and a human-readable message.

  • 400Bad RequestInvalid request, or targeting outside the allowed list (e.g. an audience of people).
  • 401UnauthorizedMissing or invalid API key.
  • 403ForbiddenInsufficient scope for this operation.
  • 404Not FoundResource not found.
  • 429Too Many RequestsRate limit exceeded — retry after Retry-After.
  • 500Server ErrorError on Echomi's side. Retry with exponential backoff.

Rate limits

Limits are set per account during the beta and shared with your keys. Every response carries the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; beyond them, the API returns 429 with a Retry-After header.

Pagination

List endpoints use cursor pagination. Pass limit (max 100) and cursor; the response includes has_more and next_cursor.

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

Ready to build?

Join the advertiser beta: we'll come back to you with your test and live keys.