Destinations / Create handoff

Create handoff

POST/v1/handoffs

Start a connect popup for OAuth destinations like Google Ads. Returns a url to send the user to; they authorize in their browser, then you poll the handoff until status is completed.

Body parameters

purpose

string · required

connect_destination or add_card.

destination_type

string

Which platform to connect, e.g. google-ads.

Response fields

string

Prefixed handoff id, e.g. hdf_7Yk2….

url

string

The popup URL to send the user to.

status

string

pending, completed, or canceled.

POST/v1/handoffs

curl https://app.converly.io/api/v1/handoffs \
  -H "Authorization: Bearer sk_live_…" \
  -d '{
    "purpose": "connect_destination",
    "destination_type": "google-ads"
  }'

201 Created

{
  "id": "hdf_7Yk2…",
  "url": "https://app.converly.io/handoff/hdf_7Yk2…",
  "status": "pending"
}