​

Audience activation pipelines

​

1. What an activation contains

• The source segment id the run resolves membership from.
• The target — an ad platform’s audience id (Custom Audience, user list, DMP segment) reached over a Nango OAuth connection, or your webhook URL, signed per delivery.
• Identifiers per member mapped to destination fields. Ad networks take hashed email/phone/name/address/mobile-id columns; a webhook receives the identifiers you forward. Either way, every member needs at least one strong identifier (email, work email, phone, or mobile advertising id) — rows with only a name are rejected, not silently dropped.
• A refresh cadence (schedule_minutes) — null means manual runs only.
• Run history and status per activation, per destination (ok, partial, failed, skipped).

​

2. Prerequisites

• A saved segment (POST /api/v1/contacts/segments) — set auto_refresh so membership the activation re-reads is current.
• Target credentials: an OAuth connection to the ad network (registered in Orbit as a Nango connection id), or an HTTPS webhook URL you control.
• Roles: owner, admin, or developer on the API key for every config and activate call.
• Consent and suppression hygiene: members flagged consent: false/suppressed: true fail the pre-activation gate below its thresholds — keep those flags honest at ingest.

​

3. Create the activation config

curl -X PATCH https://api.orbit.devotel.io/api/v1/cdp/audience/config/google \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "nango_connection_id": "conn_googleads_7d2e",
    "audience_id": "ul_91428",
    "segment_id": "seg_churn_tier1",
    "schedule_minutes": 1440
  }'

curl -X PATCH https://api.orbit.devotel.io/api/v1/cdp/audience/webhook \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "target_url": "https://edge.exampleco.io/orbit-segment-sync",
    "signing_secret": "wss_live_example_rotate_me",
    "segment_id": "seg_winback_30d"
  }'

​

4. Run an activation

curl -X POST https://api.orbit.devotel.io/api/v1/cdp/audience/activate/google \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "seg_churn_tier1",
    "operation": "add",
    "members": [
      { "email": "ada@example.com", "phone": "+14155550123" },
      { "madid": "a1b2c3d4-e5f6-47a2-91c1-55d0ab2d9c01" }
    ]
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/cdp/audience/webhook/activate \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "seg_winback_30d",
    "operation": "add",
    "members": [
      { "user_id": "u_4821", "email": "ada@example.com", "traits": { "tier": "vip" } }
    ]
  }'

​

5. Read status and failures

curl https://api.orbit.devotel.io/api/v1/cdp/audience/activations \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl https://api.orbit.devotel.io/api/v1/cdp/audience/activations/4e3b9c1d-... \
  -H "X-API-Key: dv_live_sk_your_key_here"

• ok — every batch the network accepted.
• partial — some batches failed; the member-level detail names why.
• failed — nothing accepted (quota breach, revoked token).
• skipped — nothing matchable, or no connection wired at dispatch time.

​

6. Cadence and delta updates

• add — newest members; acquisition or seeding a lookalike.
• remove — suppression; drop existing customers from prospecting spend.

​

7. Patterns

• Churn-tier → ads. A churn-risk segment refreshes daily into a Google customer-match list; auto-suppress your own customers from prospecting.
• VIP → email or ads. A high-LTV segment synced on a slow cadence (weekly) — refresh noise is worth less than accuracy here.
• Win-back → webhook sink. Fan a lapsed-customer segment into your in-house orchestration endpoint; stack it on top of segment-triggered journeys so onboard entry and offboard suppression stay on one membership definition.
• Incrementality. Set holdout_pct on the destination so the report can separate exposed conversions from a randomized control arm.

​

8. Troubleshooting

• 409 CONNECTION_NOT_CONFIGURED / PLATFORM_NOT_ENABLED / AUDIENCE_NOT_CONFIGURED. The destination is not fully wired — enable it with an audience_id and (for ad networks) a nango_connection_id. Direct API PATCHes get the same precondition the dashboard enforces.
• 422 AUDIENCE_PREFLIGHT_BLOCKED. Gate rejected the batch — too small, low identifier coverage, or consent/suppression violations. The failing check ids come back in the response; re-check POST .../preflight/:platform, then adjust the segment, the thresholds, or override deliberately.
• 400 naming a field. Off-schema input — the message is field-prefixed (e.g. holdout_pct: ...), so read which key was refused.
• Run status skipped with dispatch_skipped equal to your batches. No connection was resolved at dispatch — a cleared or never-wired nango_connection_id. Re-wire and retry the run.
• Run status failed, error mentions quota / auth. The ad-network call was rejected (quota breach or a stale OAuth token). Refresh the connection token, wait out the quota window, then POST .../retry; only ok runs are refused as already-dispatched.
• Zero matched members. The batch arrived with no strong identifier per row (name+address only). Resolve before activate — either the segment filter picks up empty profiles, or the field mapping at ingest is broken. A blank export downstream typically means exactly this.
• Approval queue hangs. Maker-checker is on (GET .../approvals/settings shows require_activation_approval: true): request → approve → re-submit with the approval id. A supervisor cannot self-approve — a second person must sign.

​

See also

• CDP audiences: build segments — the segment recipe every activation reads
• Build a segment-triggered journey — onboard offboard flows on segment membership
• Ad-hoc audience CSV export — when you need the rows once, not a pipeline
• Ads API reference — Meta ads loop (campaign, attribution)
• Reverse-ETL warehouse exports — publish segments to a warehouse instead