Primary navigation

Suggested
API Dashboard
Try ChatGPT

API partner setup

Configure client accounts, conversions, and campaigns with the Ads API.

API partners can use the Ads API to configure measurement and campaign resources for client accounts. Use the API key associated with the client ad account for every request in this guide.

Before you begin

You need:

  • An Ads API key for the client ad account.
  • Access to the client’s website and brand assets.
  • A server-side secret manager for the Ads API key and any Conversions API keys you create.

Send requests to https://api.ads.openai.com/v1. Store the account’s Ads API key in OPENAI_ADS_API_KEY for the examples in this guide.

Brand updates, pixel management, and Conversions API key creation must be enabled for the client account. If a brand update returns 403, or /conversions/pixels or /conversions/api_keys returns 404 with Not found, contact your OpenAI partner representative. A Client data source not found response means an event setting references a source that does not exist in the current ad account.

1. Confirm account access

Use GET /ad_account to verify that the key is associated with the intended client account:

curl -X GET "https://api.ads.openai.com/v1/ad_account" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"
{
  "id": "adacct_123",
  "name": "Acme Ads",
  "url": "https://www.acme.example",
  "preview_url": null,
  "status": "active",
  "timezone": "America/New_York",
  "currency_code": "USD",
  "review": {
    "status": "approved"
  }
}

Check the account name, URL, time zone, and currency before you create campaign resources. Contact your OpenAI partner representative if the account details or API access are incorrect.

2. Add a brand favicon

An account cannot serve ads until its brand review is approved. If review.reason is missing_favicon, upload and assign a favicon before you create active campaign resources.

First, upload an image with purpose set to account_favicon. The image must be at least 128 × 128 pixels. You can pass the client’s website URL and let the API resolve a suitable icon:

curl -X POST "https://api.ads.openai.com/v1/upload" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://www.acme.example",
    "purpose": "account_favicon"
  }'

Save the returned file_id, then assign it to the account:

curl -X POST "https://api.ads.openai.com/v1/ad_account/brand" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "favicon_file_id": "file_123"
  }'

The brand update starts a review. Poll GET /ad_account until review.status is approved. If the status is rejected, use review.reason to correct the brand metadata before you activate a campaign.

3. Configure conversions

Create conversion resources before you instrument the client’s site.

First, create a web pixel:

curl -X POST "https://api.ads.openai.com/v1/conversions/pixels" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme website",
    "client_type": "web"
  }'

Save both returned identifiers. Use id when you create an event setting and use pixel_id when you send conversion events.

{
  "id": "clidsrc_123",
  "client_type": "web",
  "name": "Acme website",
  "pixel_id": "134534..."
}

Next, create a server-side Conversions API key:

curl -X POST "https://api.ads.openai.com/v1/conversions/api_keys" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme production conversions"
  }'

Store the returned api_key in a server-side secret manager. Use this key only to send conversion events; do not expose it in browser code.

Finally, define the conversion event you want to measure or optimize for:

curl -X POST "https://api.ads.openai.com/v1/conversions/event_settings" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchases",
    "event_type": "order_created",
    "attribution_window_days": 30,
    "source_ids": ["clidsrc_123"]
  }'

Save the returned event setting id. For endpoint fields and responses, see Conversion setup. To implement event delivery, use the JavaScript Pixel, the Conversions API, or both with shared event IDs for deduplication.

4. Create campaigns and ads

Follow the Ads API quickstart to create a campaign, ad group, creative asset, and ad in the correct order. For partner setup, create the campaign as paused instead of active, then activate it after all child resources are ready.

Create campaigns as paused while you add and validate their ad groups and ads. Activate the campaign only after all child resources are ready.

Next steps