Ads API

The Ads API lets you manage advertising across 6 networks: Meta, Google, LinkedIn, TikTok, Pinterest, X.

Boost a post

The simplest: turn an existing post into an ad.

{
  "postId": "post_xxx",
  "platforms": ["meta", "tiktok"],
  "budget": { "amount": 50, "currency": "USD" },
  "duration": "7d",
  "targeting": {
    "countries": ["FR", "BE"],
    "ageMin": 18,
    "ageMax": 65,
    "interests": ["tech", "marketing"]
  }
}

Response:

{
  "boostId": "bst_xxx",
  "campaigns": [
    { "platform": "meta", "campaignId": "cmp_meta_xxx", "status": "active" },
    { "platform": "tiktok", "campaignId": "cmp_tiktok_xxx", "status": "active" }
  ],
  "estimatedReach": { "min": 5000, "max": 15000 }
}

Create standalone ad

For an ad not linked to a post:

{
  "platforms": ["meta"],
  "creative": {
    "headline": "Get -20%",
    "text": "Limited offer",
    "imageUrl": "https://example.com/ad.jpg",
    "cta": "SHOP_NOW",
    "destinationUrl": "https://shop.com/sale"
  },
  "budget": { "amount": 100, "currency": "USD", "type": "daily" },
  "targeting": { "countries": ["FR"] }
}

CTWA ad (Click-to-WhatsApp)

{
  "platforms": ["meta"],
  "creative": { "text": "Click to chat", "imageUrl": "..." },
  "whatsappNumber": "+33612345678",
  "budget": { "amount": 50, "currency": "USD" }
}

Campaigns CRUD

GET /v1/ads/campaigns
GET /v1/ads/campaigns/{id}
PATCH /v1/ads/campaigns/{id}
DELETE /v1/ads/campaigns/{id}

Ad sets

Custom audiences

{
  "name": "Existing customers",
  "platforms": ["meta", "google"],
  "type": "customer_list",
  "customerList": [
    { "email": "alice@example.com" },
    { "email": "bob@example.com" }
  ]
}

Lead forms

{
  "platform": "meta",
  "name": "Lead magnet Q3",
  "questions": [
    { "type": "email", "label": "Email", "required": true },
    { "type": "text", "label": "Company" }
  ],
  "privacyUrl": "https://example.com/privacy",
  "thankYouMessage": "Thanks!"
}

Received leads are notified via the ads.lead.received webhook.

Conversion events

To track conversions (Meta Pixel, Google Ads):

{
  "platform": "meta",
  "eventName": "Purchase",
  "value": 49.90,
  "currency": "USD",
  "userEmail": "sha256_hashed_email"
}

Reach estimate

{
  "platforms": ["meta"],
  "targeting": { "countries": ["FR"], "ageMin": 18, "ageMax": 65 },
  "budget": { "amount": 50, "currency": "USD" }
}

{
  "estimates": [
    { "platform": "meta", "minReach": 5000, "maxReach": 15000 }
  ]
}

Targeting search

Returns interests, behaviors, demographics matching the search.

Tracking tags (UTM)

{
  "name": "Summer campaign",
  "utm": {
    "source": "pepe",
    "medium": "social",
    "campaign": "summer2026"
  }
}

All your ad URLs will be automatically decorated.

Analytics

{
  "data": [
    {
      "campaignId": "cmp_xxx",
      "impressions": 45200,
      "clicks": 870,
      "ctr": 0.019,
      "spend": 124.50,
      "cpc": 0.143,
      "conversions": 32,
      "cpa": 3.89,
      "roas": 4.2
    }
  ]
}

DSA compliance

For Meta Ads in the EU, generate the DSA report: