Destinations / Create OAuth handoff

Create OAuth handoff

POST/v1/destinations/oauth-handoffs

Start an OAuth connection for Google Ads or GA4. Returns a url to send the user to. For Google Ads it is a Converly-hosted connect page; for GA4 it is a Google consent URL. Open it without rewriting it, then poll the handoff with Get handoff until status is completed. Links expire after 30 minutes. Other platforms connect through Create handoff.

Body parameters

destination_type

string · required

google-ads or google-analytics.

return_url

string

Where to send the user after OAuth completes. Optional.

site_id

string

The site to connect it to. Required for account-wide keys on multi-site accounts, otherwise 400 site_id_required.

Response fields

string

Prefixed handoff id, e.g. hdf_7Yk2….

url

string

The page to send the user to.

status

string

pending, completed, or canceled.

POST/v1/destinations/oauth-handoffs

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

201 Created

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