Create bridge transfer

What it does

Request

POST /bridge-transfers on https://api.apogee.ad/api/v1.

Headers

• Authorization string header required

  Bearer apk_…: an API key with the scope of this route.

• Idempotency-Key string header required

  A unique key per request, e.g. a UUID, reused when you retry it: the first answer comes back instead of a second write (idempotency).

  1 to 255 visible ASCII characters

• Content-Type string header required

  application/json

Body

• source object required

  Where the ads come from: one of ad_ids, adset_ids, campaign_ids

  Fields (5)

  • platform string required

    One of meta, tiktok, snapchat

  • ad_account_id string required

    The ad account (list_ad_accounts): Meta act_…, a TikTok advertiser id, a Snapchat ad account id

    Matches ^(act_\d{1,32}|[A-Za-z0-9][A-Za-z0-9-]{0,63})$

  • ad_ids array of strings optional

    The ads to transfer (cross-platform: 50 max per run)

    1 to 100 items

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • adset_ids array of strings optional

    Meta: ad sets (cross-platform: their ads; Meta → Meta: the ad sets themselves, 20 max)

    1 to 20 items

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • campaign_ids array of strings optional

    Meta: campaigns (cross-platform: their ads; Meta → Meta: the campaigns themselves, 5 max)

    1 to 5 items

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

• destination object required
  Fields (5)

  • platform string required

    One of meta, tiktok, snapchat

  • ad_account_id string required

    The ad account (list_ad_accounts): Meta act_…, a TikTok advertiser id, a Snapchat ad account id

    Matches ^(act_\d{1,32}|[A-Za-z0-9][A-Za-z0-9-]{0,63})$

  • campaign_id string optional

    Required, except for a Meta → Meta copy of campaigns

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • adset_id string optional

    An existing destination ad set / TikTok ad group / Snapchat ad squad (list_adsets)

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • new_adset object optional

    Cross-platform: a new ad set copied from a template, instead of adset_id

    Fields (3)

    • template_adset_id string required

      An ad set / ad group / ad squad of the destination campaign whose settings the new one copies

      Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

    • name string required

      1 to 255 characters

    • daily_budget number optional

      Account currency; not for a TikTok CBO campaign

      > 0

• launch_status string optional

  Cross-platform. Default CREATED_PAUSED; SCHEDULED_* only with new_adset (+ schedule)

  One of CREATED_PAUSED, LIVE_NOW, SCHEDULED_PAUSED, SCHEDULED_LIVE

• schedule object optional

  A new ad set's schedule, in the destination account's time zone

  Fields (4)

  • date string required

    Matches ^\d{4}-\d{2}-\d{2}$

  • time string required

    Matches ^\d{2}:\d{2}$

  • end_date string optional

    Matches ^\d{4}-\d{2}-\d{2}$

  • end_time string optional

    Matches ^\d{2}:\d{2}$

• extra_fields object optional

  What the plan asked for (recap.missing): the destination's identity / profile / page, URL, CTA, headline

  Fields (8)

  • identity_id string optional

    TikTok: the identity the ads run under

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • identity_type string optional

    TikTok: one of the brand's TikTok accounts, TT_USER or BC_AUTH_TT through its Business Center (TikTok refuses a custom identity on these ads)

    One of TT_USER, BC_AUTH_TT

  • identity_bc_id string optional

    TikTok BC_AUTH_TT: the Business Center

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • profile_id string optional

    Snapchat: the public profile

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • page_id string optional

    Meta: the Facebook page

    Matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  • website_url string optional

    up to 2,048 characters

  • call_to_action string optional

    up to 40 characters

  • headline string optional

    Snapchat: 34 characters

    up to 255 characters

• meta_texts map optional

  Destination Meta: each source ad's texts (by source ad id), instead of the ones the plan suggested (recap.meta_texts)

  Keys match ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

  Each value: object

  Fields (3)

  • primary_text string optional

    up to 2,200 characters

  • headline string optional

    up to 255 characters

  • description string optional

    up to 255 characters

• options object optional

  Meta → Meta copy only

  Fields (3)

  • keep_social_proof boolean optional

    Default true: reuse the source post (likes, comments) when Meta allows it

  • status string optional

    After the copy: PAUSED (default), ACTIVE, or INHERIT (on only what is on in the source)

    One of PAUSED, ACTIVE, INHERIT

  • name_suffix string optional

    up to 100 characters

• mapping map optional

  Meta → Meta copy: values for the plan's fields (recap.fields: pixel, page, audience, budget…), by key

  Each value: string

Response

201.

• id string
• status string

  One of prepared

• ready boolean
• recap object
• ask string

  When not ready: what to give, then prepare it again

• expires_at string (date-time)

Every answer carries X-Request-Id (give it to support), Apogee-Version: 2026-10-06, and the RateLimit and RateLimit-Policy headers; a replayed answer also carries Idempotent-Replayed: true.

Errors

Errors are application/problem+json with a stable code to switch on (all the codes).

Example

With your key in APOGEE_API_KEY (create one):

curl -X POST 'https://api.apogee.ad/api/v1/bridge-transfers' \
  -H "Authorization: Bearer $APOGEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "platform": "meta",
    "ad_account_id": "act_1234567890",
    "ad_ids": [
      "120200000000000003"
    ]
  },
  "destination": {
    "platform": "tiktok",
    "ad_account_id": "7000000000000000001",
    "campaign_id": "1800000000000000001",
    "adset_id": "1800000000000000002"
  }
}'

{
  "id": "120200000000000001",
  "status": "prepared",
  "ready": false,
  "recap": {},
  "ask": "120200000000000001",
  "expires_at": "2026-10-23T09:00:00.000Z"
}

Access and cost

In the MCP

An AI assistant does the same with this tool of the MCP server:

• prepare_bridge_transfer: Prepares a transfer without transferring anything: the source ads (or a Meta ad set's or campaign's ads), the destination campaign and its existing ad set / ad group / ad squad or a new one copied from a template. Returns the recap and a plan_id; ready: false lists what to ask (a TikTok identity, a Snapchat public profile, a website…), then prepare again with extra_fields. Incompatibilities are listed: your yes accepts them. For a Meta → Meta copy, the destination's fields go in mapping.

Related operations

• Confirm bridge transfer: POST /bridge-transfers/{id}/confirm
• Get bridge transfer: GET /bridge-transfers/{id}
• List bridged ads: GET /bridged-ads
• Get bridge stats: GET /bridged-ads/stats
• Get bridge daily stats: GET /bridged-ads/daily-stats