Ads API

Connect a Meta Ad Account and run the full advertising loop from Orbit: create click-to-chat campaigns, forward conversions back to Meta for closed-loop attribution, turn Meta Lead Ads into contacts, and activate CDP segments as hashed Custom Audiences. Base path: /api/v1/ads Authentication: API key (X-API-Key) or session JWT. Every endpoint requires authentication. Roles: read endpoints (connection status, campaign list/detail, audience list) are open to any authenticated role. Every write — connecting, disconnecting, campaign create/update/delete, Conversions API calls, Lead Ads ingestion, and audience create/sync/delete — requires the owner or admin role. A single Meta Ad Account is stored per organization. Connect it first; the other endpoints return CHANNEL_UNAVAILABLE until a connection (and, for Conversions, a dataset ID) exists.

Connection

Connect via the hosted OAuth flow (/oauth/exchange, used by the in-app callback) or by posting an access token and ad account id directly (/connect).

Method	Path	Purpose	Role
`POST`	`/api/v1/ads/oauth/exchange`	Exchange a Facebook OAuth `code` for a long-lived token and connect the first ad account	owner / admin
`POST`	`/api/v1/ads/connect`	Connect using an existing `access_token` and `ad_account_id`	owner / admin
`GET`	`/api/v1/ads/status`	Connection summary: `connected`, `ad_account_id`, `connected_at`, account `currency`	any role
`DELETE`	`/api/v1/ads/disconnect`	Remove the Meta Ad Account connection	owner / admin

Tokens are encrypted at rest. The status response surfaces the selected ad account’s currency so budgets and spend render in the account’s own currency rather than defaulting to USD.

Campaigns

Click-to-chat campaigns drive WhatsApp, Messenger, or Instagram Direct conversations. New campaigns are created in PAUSED state so you can review them in Meta before they spend.

Method	Path	Purpose	Role
`GET`	`/api/v1/ads/campaigns`	List campaigns for the connected ad account (cursor-paginated). Returns an empty list when no account is connected.	any role
`POST`	`/api/v1/ads/campaigns`	Create a click-to-chat campaign (`destination`: `WHATSAPP`, `MESSENGER`, or `INSTAGRAM_DIRECT`)	owner / admin
`GET`	`/api/v1/ads/campaigns/{id}`	Campaign detail with Meta insights	any role
`PUT`	`/api/v1/ads/campaigns/{id}`	Update name, status (`ACTIVE`/`PAUSED`/`ARCHIVED`), daily budget, or targeting	owner / admin
`DELETE`	`/api/v1/ads/campaigns/{id}`	Delete a campaign	owner / admin

Conversions API

Forward business outcomes (lead, purchase, registration, appointment) from WhatsApp conversations that started on a click-to-WhatsApp ad back to Meta, closing the attribution loop. Email and phone are SHA-256 hashed before they leave Orbit — raw PII is never sent to Meta. Set a dataset_id once; the test and live endpoints both read it.

Method	Path	Purpose	Role
`PUT`	`/api/v1/ads/conversions/dataset`	Set or replace the Conversions API `dataset_id`	owner / admin
`POST`	`/api/v1/ads/conversions/test`	Send a test event to verify the integration	owner / admin
`POST`	`/api/v1/ads/conversions`	Post a real conversion event (include `ctwa_clid` for ad attribution)	owner / admin

A conversion must carry at least one identifier in user_data — phone, email, external_id, or ctwa_clid — for Meta to match it.

Lead Ads ingestion

Turn a Meta leadgen webhook batch into tenant contacts. Each lead’s instant-form answers are fetched from the Graph API and upserted through the same dedup, compliance, and required-field machinery as a CSV import. Leads with no email and no phone are skipped; one failed fetch never drops the rest of the batch.

Method	Path	Purpose	Role
`POST`	`/api/v1/ads/leads/ingest`	Ingest one Meta `leadgen` webhook batch into contacts	owner / admin

The response reports received, fetched, fetch_failures, skipped_no_contact, created, updated, and duplicates.

Custom Audiences

Activate a first-party CDP segment to Meta as a hashed customer-list Custom Audience for targeting or suppression, then keep it in sync as the segment recomputes. Membership is SHA-256 hashed before upload.

Method	Path	Purpose	Role
`POST`	`/api/v1/ads/audiences`	Create a Custom Audience, optionally linked to a CDP `segment_id`	owner / admin
`GET`	`/api/v1/ads/audiences`	List the audiences this org has activated, with segment links and sync metadata	any role
`POST`	`/api/v1/ads/audiences/{audienceId}/sync`	Sync segment membership — `mode: "add"` (default) uploads members, `mode: "remove"` suppresses them	owner / admin
`DELETE`	`/api/v1/ads/audiences/{audienceId}`	Delete the audience from Meta and drop the stored mapping	owner / admin

A sync resolves up to 100,000 members per call; larger segments are truncated and the response sets truncated: true.

Recipes

Step-by-step request/response examples for the full advertising loop. Every response lands in the standard envelope (data + meta.request_id/meta.timestamp); the JSON below shows the data payload. The Node snippets call each endpoint through the SDK’s generic request helper — see the Node.js SDK page.

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

Create a click-to-chat campaign — POST /ads/campaigns

Create the campaign in one call. Orbit always submits it to Meta in PAUSED state, so you can review it before it spends; flip it to ACTIVE with PUT /ads/campaigns/{id} when you’re ready.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/campaigns \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "August CTWA — New Leads",
    "objective": "OUTCOME_LEADS",
    "daily_budget": 50,
    "destination": "WHATSAPP",
    "ad_text": "Chat with us on WhatsApp to get started.",
    "welcome_message": "Hi! How can we help you today?",
    "image_url": "https://cdn.example.com/ads/august-hero.png",
    "targeting": { "countries": ["US"], "age_min": 18, "age_max": 65 }
  }'

const created = await orbit.request("POST", "/ads/campaigns", {
  name: "August CTWA — New Leads",
  objective: "OUTCOME_LEADS",
  daily_budget: 50,
  destination: "WHATSAPP",
  ad_text: "Chat with us on WhatsApp to get started.",
  welcome_message: "Hi! How can we help you today?",
  image_url: "https://cdn.example.com/ads/august-hero.png",
  targeting: { countries: ["US"], age_min: 18, age_max: 65 },
});
// created.data.id — the Meta campaign id

201:

{
  "id": "1202984756203847",
  "destination": "WHATSAPP",
  "ad_text": "Chat with us on WhatsApp to get started.",
  "welcome_message": "Hi! How can we help you today?",
  "image_url": "https://cdn.example.com/ads/august-hero.png",
  "targeting": { "countries": ["US"], "age_min": 18, "age_max": 65 }
}

The id is Meta’s campaign id — the same id you pass to GET/PUT/DELETE /ads/campaigns/{id}.

Set the Conversions API dataset — PUT /ads/conversions/dataset

Set once before posting any conversion. The dataset_id only accepts letters, digits, underscores, and hyphens.

curl -X PUT https://api.orbit.devotel.io/api/v1/ads/conversions/dataset \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "dataset_id": "8294038739821234" }'

const dataset = await orbit.request("PUT", "/ads/conversions/dataset", {
  dataset_id: "8294038739821234",
});
// dataset.data.updated === true

200:

{ "dataset_id": "8294038739821234", "updated": true }

Verify CAPI delivery — POST /ads/conversions/test

No request body. Sends a test event to Meta so you can check Test Events in Events Manager before posting real traffic.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/conversions/test \
  -H "X-API-Key: dv_live_sk_your_key_here"

const test = await orbit.request("POST", "/ads/conversions/test");
// test.data.events_received === 1

200:

{ "events_received": 1, "fbtrace_id": "ABw1234defg56789hijk" }

Forward a conversion — POST /ads/conversions

When a click-to-WhatsApp conversation reaches a business outcome, replay it to Meta for closed-loop attribution. The ctwa_clid is the click id Meta attaches to the first inbound message of an ad-originated conversation — include it whenever you have it so Meta can join the conversion back to the ad. Every user_data value is hashed (SHA-256) before it leaves Orbit; raw PII is never sent to Meta. A conversion must carry at least one identifier — phone, email, external_id, or ctwa_clid.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/conversions \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "Purchase",
    "event_time": 1787647200,
    "messaging_channel": "whatsapp",
    "user_data": {
      "phone": "+14155552671",
      "ctwa_clid": "ARbU5uq0XJtNLP5Sr4Qv-6C0EW0eswIWQ85XsimbawX1WsDx70VGx2nE5Ywl6o2Y"
    },
    "custom_data": { "value": 149.90, "currency": "USD" }
  }'

const posted = await orbit.request("POST", "/ads/conversions", {
  event_name: "Purchase",
  event_time: 1787647200,
  messaging_channel: "whatsapp",
  user_data: {
    phone: "+14155552671",
    ctwa_clid:
      "ARbU5uq0XJtNLP5Sr4Qv-6C0EW0eswIWQ85XsimbawX1WsDx70VGx2nE5Ywl6o2Y",
  },
  custom_data: { value: 149.9, currency: "USD" },
});
// posted.data.events_received === 1

200:

{ "events_received": 1, "fbtrace_id": "ABw0987zyx654wvuts" }

event_time is optional and defaults to the current time. Other outcomes map to Lead, CompleteRegistration, Schedule, or Contact; messaging_channel accepts whatsapp (default), messenger, or instagram.

Ingest a Lead Ads batch — POST /ads/leads/ingest

Replay one Meta leadgen page-webhook delivery and turn it into tenant contacts. The webhook carries only lead references — Orbit fetches each lead’s instant-form answers from Meta with your connected token, then upserts through the same machinery as a contacts import.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/leads/ingest \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "object": "page",
    "entry": [
      {
        "id": "412345678901234",
        "time": 1787647200,
        "changes": [
          {
            "field": "leadgen",
            "value": {
              "leadgen_id": "1293847560392018",
              "form_id": "88765432109876",
              "ad_id": "1202984756203847",
              "page_id": "412345678901234",
              "created_time": 1787647200
            }
          }
        ]
      }
    ]
  }'

const ingest = await orbit.request("POST", "/ads/leads/ingest", {
  object: "page",
  entry: [
    {
      id: "412345678901234",
      time: 1787647200,
      changes: [
        {
          field: "leadgen",
          value: {
            leadgen_id: "1293847560392018",
            form_id: "88765432109876",
            ad_id: "1202984756203847",
            page_id: "412345678901234",
            created_time: 1787647200,
          },
        },
      ],
    },
  ],
});
// ingest.data.created | ingest.data.fetch_failures

200:

{
  "received": 1,
  "fetched": 1,
  "fetch_failures": 0,
  "skipped_no_contact": 0,
  "created": 1,
  "updated": 0,
  "duplicates": 0
}

Leads with no email and no phone land in skipped_no_contact; a lead whose Graph fetch fails lands in fetch_failures and never drops the rest of the batch. Re-submitted leads count under updated, not duplicates (upsert merge).

Create a Custom Audience — POST /ads/audiences

Create the Meta Custom Audience and link it to a CDP segment_id so later syncs resolve membership automatically.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/audiences \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-intent — Orbit CDP",
    "description": "Segment activation from Orbit CDP",
    "segment_id": "seg_high_intent_90d"
  }'

const audience = await orbit.request("POST", "/ads/audiences", {
  name: "High-intent — Orbit CDP",
  description: "Segment activation from Orbit CDP",
  segment_id: "seg_high_intent_90d",
});
// audience.data.audience_id — pass to /audiences/{audienceId}/sync

201:

{
  "audience_id": "23846378900120354",
  "name": "High-intent — Orbit CDP",
  "segment_id": "seg_high_intent_90d",
  "created_at": "2026-08-25T12:00:00.000Z",
  "last_synced_at": null,
  "last_sync_count": null
}

Sync segment membership — POST /ads/audiences/{audienceId}/sync

Upload (mode: "add", the default) or suppress (mode: "remove") the segment’s current membership. Identifiers are SHA-256 hashed before upload; raw email and phone never leave Orbit. Up to 100,000 members resolve per call — a larger segment is truncated and the response sets truncated: true. Omit segment_id to reuse the segment linked at create time.

curl -X POST https://api.orbit.devotel.io/api/v1/ads/audiences/23846378900120354/sync \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "add" }'

# Suppression — remove the segment from the audience instead:
curl -X POST https://api.orbit.devotel.io/api/v1/ads/audiences/23846378900120354/sync \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "remove" }'

const synced = await orbit.request(
  "POST",
  "/ads/audiences/23846378900120354/sync",
  { mode: "add" },
);
// synced.data.sent | synced.data.truncated

const suppressed = await orbit.request(
  "POST",
  "/ads/audiences/23846378900120354/sync",
  { mode: "remove" },
);

200:

{
  "audience_id": "23846378900120354",
  "segment_id": "seg_high_intent_90d",
  "mode": "add",
  "matched": 12480,
  "sent": 12480,
  "batches": 2,
  "num_received": 12465,
  "truncated": false
}

matched counts resolved members with at least one identifier, sent what Meta was handed, and num_received sums Meta’s per-batch acknowledgements — a small gap between them is normal (Meta dedupes). When truncated is true, only the first 100,000 members were pushed.

Delete a Custom Audience — DELETE /ads/audiences/{audienceId}

Removes the audience at Meta and drops Orbit’s stored link. Returns 204 No Content.

curl -i -X DELETE https://api.orbit.devotel.io/api/v1/ads/audiences/23846378900120354 \
  -H "X-API-Key: dv_live_sk_your_key_here"

await orbit.request("DELETE", "/ads/audiences/23846378900120354");

API Reference

All Endpoints

Meta Ads API: click-to-chat, CAPI, and Lead Ads

Ads API

Connection

Campaigns

Conversions API

Lead Ads ingestion

Custom Audiences

Recipes

Create a click-to-chat campaign — POST /ads/campaigns

Set the Conversions API dataset — PUT /ads/conversions/dataset

Verify CAPI delivery — POST /ads/conversions/test

Forward a conversion — POST /ads/conversions

Ingest a Lead Ads batch — POST /ads/leads/ingest

Create a Custom Audience — POST /ads/audiences

Sync segment membership — POST /ads/audiences/{audienceId}/sync

Delete a Custom Audience — DELETE /ads/audiences/{audienceId}

See also

​Ads API

​Connection

​Campaigns

​Conversions API

​Lead Ads ingestion

​Custom Audiences

​Recipes

​Create a click-to-chat campaign — POST /ads/campaigns

​Set the Conversions API dataset — PUT /ads/conversions/dataset

​Verify CAPI delivery — POST /ads/conversions/test

​Forward a conversion — POST /ads/conversions

​Ingest a Lead Ads batch — POST /ads/leads/ingest

​Create a Custom Audience — POST /ads/audiences

​Sync segment membership — POST /ads/audiences/{audienceId}/sync

​Delete a Custom Audience — DELETE /ads/audiences/{audienceId}

​See also

Ads API

Connection

Campaigns

Conversions API

Lead Ads ingestion

Custom Audiences

Recipes

Create a click-to-chat campaign — POST /ads/campaigns

Set the Conversions API dataset — PUT /ads/conversions/dataset

Verify CAPI delivery — POST /ads/conversions/test

Forward a conversion — POST /ads/conversions

Ingest a Lead Ads batch — POST /ads/leads/ingest

Create a Custom Audience — POST /ads/audiences

Sync segment membership — POST /ads/audiences/{audienceId}/sync

Delete a Custom Audience — DELETE /ads/audiences/{audienceId}

See also