Skip to main content
Before you can manage campaigns on a platform, you need to connect your ad account for that platform. Each platform uses OAuth to grant AdRelay access to your ad accounts.

​
OAuth Flow by Platform

curl -X GET "https://api.adrelay.dev/v1/connections/google_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
Scopes requested: Google Ads API read/write access. The user must have a Google Ads manager or standard account.

​
Meta Ads

curl -X GET "https://api.adrelay.dev/v1/connections/meta_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
Scopes requested: ads_management, ads_read. The user must be an admin or advertiser on the Meta Business account.

​
TikTok Ads

curl -X GET "https://api.adrelay.dev/v1/connections/tiktok_ads/authorize" \
  -H "X-API-Key: $ADRELAY_API_KEY"
Scopes requested: Campaign management read/write. The user must have access to a TikTok Ads Manager account.

​
Completing the OAuth Flow

Each authorize endpoint returns a JSON response with a redirect URL: 
{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...",
  "platform": "google_ads"
}
Direct the user to the authorize_url in their browser. After granting access, they will be redirected back to AdRelay, and the connection will be established automatically.

​
Syncing Accounts

After connecting a platform, trigger a sync to pull in account data: 
curl -X POST "https://api.adrelay.dev/v1/connections/sync" \
  -H "X-API-Key: $ADRELAY_API_KEY"
This refreshes the connection’s account data and updates the connection status. You should sync after initial connection and periodically to keep data fresh.

​
Connection Statuses

StatusDescription
ACTIVEConnection is healthy. Tokens are valid and API calls will succeed.
PENDINGOAuth flow has been initiated but not yet completed by the user.
REVOKEDAccess has been revoked by the user or tokens have expired beyond refresh. Re-authorization is required.
ERRORAn error occurred with the connection. Check the connection details for more information.

​
Listing Connections

View all your connected accounts: 
curl -X GET "https://api.adrelay.dev/v1/connections" \
  -H "X-API-Key: $ADRELAY_API_KEY"

{
  "connections": [
    {
      "id": "conn_abc123",
      "platform": "google_ads",
      "status": "ACTIVE",
      "label": "Main Google Account",
      "remote_account_id": "123-456-7890",
      "created_at": "2026-03-01T12:00:00Z",
      "last_synced_at": "2026-03-21T08:00:00Z"
    },
    {
      "id": "conn_def456",
      "platform": "meta_ads",
      "status": "ACTIVE",
      "label": null,
      "remote_account_id": "act_987654321",
      "created_at": "2026-03-05T10:00:00Z",
      "last_synced_at": "2026-03-21T08:00:00Z"
    }
  ]
}

​
Updating a Connection

You can update a connection’s label to help identify it: 
curl -X PATCH "https://api.adrelay.dev/v1/connections/conn_abc123" \
  -H "X-API-Key: $ADRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "US Google Ads Account"}'

​
Removing a Connection

Delete a connection when you no longer need it. This revokes AdRelay’s access tokens for that platform account. 
curl -X DELETE "https://api.adrelay.dev/v1/connections/conn_abc123" \
  -H "X-API-Key: $ADRELAY_API_KEY"
Deleting a connection does not delete campaigns on the platform. It only removes AdRelay’s access to manage them.