Create a ChatGPT chat card campaign with POST /v1/ads/create on an openaiads account. Then measure it with a pixel and the server-side conversions endpoint.

OpenAI Ads has no OAuth. You connect by posting an API key from ChatGPT Ads Manager, and one key covers exactly one ad account.

Quick reference

Property	Value
Hierarchy	Campaign > Ad group > Chat card ad, created in one call
Goals (`goal`)	`traffic`, `awareness`, `conversions`
Title (`headline`)	Required, 3 to 50 characters
Body	Required, up to 100 characters
Creative	`imageUrl` and `linkUrl`, both required, static image only
Budget	`budgetType` `daily` or `lifetime`, minimum 1 in the ad account currency
Targeting	Country only
Bidding	Maximize Results (automatic, daily budget) or a fixed bid
Conversion event	Per campaign, with `promotedObject.customEventType`
Click tracking	`tracking.urlTags` with OpenAI's URL macros
Dry run	`validateOnly: true`
Conversion tracking	Pixel plus server-side Conversions API
Performance sync	Daily impressions, clicks and spend (analytics)
Edits after creation	Status and budget (daily or lifetime) only
Boost an existing post	No, ChatGPT has no organic posts
Custom audiences	No, OpenAI exposes audiences in Ads Manager only
Product feed upload	No, feeds are managed in Ads Manager over SFTP
Video creatives	No, chat cards are images

Before you start

Create the key in ChatGPT Ads Manager under Settings. It is scoped to one ad account, so connect each ad account separately.

OpenAI opens Ads Manager to US-based businesses. The ads serve to ChatGPT Free and Go users in the United States, Canada, Australia and New Zealand.

The key you paste carries full campaign write access, because OpenAI has no read-only key scope.

Zernio uses it to read your ads and performance, and to create and manage the campaigns you set up in Zernio. Campaigns built in ChatGPT Ads Manager stay editable there.

Connect

Call POST /v1/connect/openai-ads/credentials with the key and a profileId. Zernio validates the key against OpenAI before storing anything.

Reposting a rotated key for the same ad account updates the connection in place.

The endpoint also accepts the x-connect-token header, so you can hand the flow to your own customers like every other connect endpoint.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: connected } = await zernio.connect.connectOpenAIAdsCredentials({
  body: {
    apiKey: 'sk-ads-xxxxxxxxxxxxxxxxxxxx',
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4'
  }
});

console.log(connected.accountId);

Response (200):

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "adAccountName": "Acme US"
}

The accountId is the openaiads account every sample below uses. Connecting from the Zernio dashboard, under Connections, does the same thing.

Errors. A key that cannot read an OpenAI ad account returns 401 with code invalid_credentials.

A 402 with code: "PAYMENT_REQUIRED" is a billing gate closing before the key is even checked. It is usually reason: "free_tier_exceeded": the team is past its free connected accounts with no card on file.

dashboard_url in the body is where the end user adds one (connect failures).

In this section

Create a campaign

Create a ChatGPT chat card campaign, and set its budget, status, goal, bidding, conversion event, click tracking and targeting.

Analytics

Read the daily impressions, clicks and spend Zernio syncs from OpenAI for a ChatGPT ad.

OpenAI pixel

Create an OpenAI pixel with its Conversions API key, read it, manage its conversion events and install it on a site.

Conversions API

Send server-side conversion events to an OpenAI pixel through OpenAI's Conversions API.

Manage ads

Pause or resume an OpenAI ad, change its budget, create a campaign on its own, and read each level's status.

Limits & errors

OpenAI Ads creative and account limits, what the integration does not support, and the errors it returns most often.

Connect an OpenAI Ads account: every field of the connect call.
Create standalone ad: every field of the create request.
Create a standalone campaign and Update a campaign: campaign-only create and budget edits.
Get campaign tree: the status fields per level.
Create tracking tag: pixels and Conversions API keys.
Pixels and tracking tags: the pixel API across platforms.
Send conversions and List conversion destinations.
Connecting accounts: profiles, accounts and the connect token.

Create a ChatGPT chat card campaign with POST /v1/ads/create on an openaiads account. Then measure it with a pixel and the server-side conversions endpoint.

OpenAI Ads has no OAuth. You connect by posting an API key from ChatGPT Ads Manager, and one key covers exactly one ad account.

Quick reference

Property	Value
Hierarchy	Campaign > Ad group > Chat card ad, created in one call
Goals (`goal`)	`traffic`, `awareness`, `conversions`
Title (`headline`)	Required, 3 to 50 characters
Body	Required, up to 100 characters
Creative	`imageUrl` and `linkUrl`, both required, static image only
Budget	`budgetType` `daily` or `lifetime`, minimum 1 in the ad account currency
Targeting	Country only
Bidding	Maximize Results (automatic, daily budget) or a fixed bid
Conversion event	Per campaign, with `promotedObject.customEventType`
Click tracking	`tracking.urlTags` with OpenAI's URL macros
Dry run	`validateOnly: true`
Conversion tracking	Pixel plus server-side Conversions API
Performance sync	Daily impressions, clicks and spend (analytics)
Edits after creation	Status and budget (daily or lifetime) only
Boost an existing post	No, ChatGPT has no organic posts
Custom audiences	No, OpenAI exposes audiences in Ads Manager only
Product feed upload	No, feeds are managed in Ads Manager over SFTP
Video creatives	No, chat cards are images

Before you start

Create the key in ChatGPT Ads Manager under Settings. It is scoped to one ad account, so connect each ad account separately.

OpenAI opens Ads Manager to US-based businesses. The ads serve to ChatGPT Free and Go users in the United States, Canada, Australia and New Zealand.

The key you paste carries full campaign write access, because OpenAI has no read-only key scope.

Zernio uses it to read your ads and performance, and to create and manage the campaigns you set up in Zernio. Campaigns built in ChatGPT Ads Manager stay editable there.

Connect

Call POST /v1/connect/openai-ads/credentials with the key and a profileId. Zernio validates the key against OpenAI before storing anything.

Reposting a rotated key for the same ad account updates the connection in place.

The endpoint also accepts the x-connect-token header, so you can hand the flow to your own customers like every other connect endpoint.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: connected } = await zernio.connect.connectOpenAIAdsCredentials({
  body: {
    apiKey: 'sk-ads-xxxxxxxxxxxxxxxxxxxx',
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4'
  }
});

console.log(connected.accountId);

Response (200):

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "adAccountName": "Acme US"
}

The accountId is the openaiads account every sample below uses. Connecting from the Zernio dashboard, under Connections, does the same thing.

Errors. A key that cannot read an OpenAI ad account returns 401 with code invalid_credentials.

dashboard_url in the body is where the end user adds one (connect failures).

Connect an OpenAI Ads account: every field of the connect call.
Create standalone ad: every field of the create request.
Create a standalone campaign and Update a campaign: campaign-only create and budget edits.
Get campaign tree: the status fields per level.
Create tracking tag: pixels and Conversions API keys.
Pixels and tracking tags: the pixel API across platforms.
Send conversions and List conversion destinations.
Connecting accounts: profiles, accounts and the connect token.

OpenAI Ads

Authentication details

Quick reference

Before you start

Connect

In this section

Create a campaign

Analytics

OpenAI pixel

Conversions API

Manage ads

Limits & errors

OpenAI Ads

Ads

On this page

OpenAI Ads

Authentication details

Quick reference

Before you start

Connect

In this section

Create a campaign

Analytics

OpenAI pixel

Conversions API

Manage ads

Limits & errors

OpenAI Ads

Ads

On this page