For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
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.

Conversion-optimized campaigns must also be enabled for the client account. If campaign creation returns 403 with Conversion bidding is not enabled, contact your OpenAI partner representative.

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.

To create a conversion-optimized campaign (oCPC), set bidding_type to conversions and pass exactly one event setting ID. For the bidding model, prerequisites, and reporting guidance, see Conversion-optimized campaigns.

curl -X POST "https://api.ads.openai.com/v1/campaigns" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme purchases",
    "status": "paused",
    "budget": {
      "lifetime_spend_limit_micros": 250000000
    },
    "bidding_type": "conversions",
    "conversion_event_setting_ids": ["ces_123"]
  }'

The event setting must be active, belong to the current ad account, connect to one active conversion source, and use a standard supported event such as order_created, lead_created, or registration_completed. Custom events cannot be optimization goals. For beta-enabled product-feed campaigns, use the same campaign endpoint and add mode: "product_feed" and the linked product_feed_id. You cannot change the campaign objective or selected conversion event after creation.

Next, create each ad group with billing_event_type set to click. For an oCPC campaign, max_bid_micros is the CPA bid; for example, 100000000 is a $100.00 CPA bid for a USD account.

curl -X POST "https://api.ads.openai.com/v1/ad_groups" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "cmpn_101",
    "name": "US English",
    "status": "active",
    "bidding_config": {
      "billing_event_type": "click",
      "max_bid_micros": 100000000
    }
  }'

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