Configure destinations for OpenAI Audiences

OpenAI Audiences syncs an Amperity audience to an OpenAI custom audience, so you can target, exclude, or bid-adjust those customers in your OpenAI ad campaigns. Members are matched to OpenAI users on a single hashed identifier — an email address or a phone number — that you choose when you configure the destination. The connector uses the OpenAI Advertiser API.

Beta

The OpenAI Audiences connector is currently in beta. Contact your Amperity representative to learn more.

Use OpenAI Audiences to sync an Amperity audience to an OpenAI custom audience, so you can include, exclude, or bid-adjust those customers in your OpenAI ad campaigns.

Each member is matched to OpenAI users on a single identifier that you choose when you configure the destination: an email address, a phone number, or a pre-hashed email_sha256 or phone_number_sha256 value. Amperity applies SHA-256 hashing to raw email and phone values before sending them; plaintext identifiers never leave Amperity. Email is trimmed and lowercased before hashing, and phone numbers are converted to E.164 format (including the country code) before hashing.

If you already store hashed identifiers, choose the email_sha256 or phone_number_sha256 column and Amperity sends the value as supplied, after confirming it is a 64-character SHA-256 digest. Because Amperity cannot re-normalize a value that is already hashed, a pre-hashed identifier only matches if it was hashed the way OpenAI expects: the SHA-256 of a trimmed, lowercased email, or of a phone number in E.164 format. A digest built from a differently formatted value is still a valid 64-character digest, so it passes validation but silently matches no one.

A member whose chosen identifier is missing, or cannot be used — a phone number that does not parse, or a pre-hashed value that is not a 64-character digest — is dropped and reported as a failed row, so that one bad member does not fail the whole run.

The query or segment sent to OpenAI Audiences must return the one column that matches the configured Match identifier — an email, phone, email_sha256, or phone_number_sha256 column. Any other column is ignored, not rejected.

That column is also the key Amperity uses to track audience membership, so it must stay fixed: changing the Match identifier after the audience exists means recreating the audience. A query that omits the configured column still runs — every member then fails to match and the run reports those rows as failed.

Note

This destination uses the OpenAI Advertiser API .

Important

OpenAI Audiences updates membership incrementally. Each run sends only the members who joined or left the audience since the last run: new members are added first, then members who left are removed. Members already in the audience are left in place and reported as unchanged. Amperity tracks these membership changes itself, so it never resends the full audience.

Caution

A single identifier is sent per member — the Match identifier you configure applies to every member of the audience. Because that identifier is also how Amperity tracks membership, it cannot be changed without recreating the audience, and match rates are typically lower than a connector that sends several identifiers per person. OpenAI counts a user matched on either email or phone as one member, but only one identifier column can be sent.

Note

Membership is matched in the background. A successful orchestration means OpenAI accepted the members, not that they matched a user or that the audience is usable for targeting yet. OpenAI reports matched-audience sizes only as privacy-preserving ranges and never returns per-member results, so a run cannot confirm that any specific member matched — confirm the audience size in OpenAI Ads Manager.

Caution

Amperity resolves the List name to an audience on the account, creating one if it does not exist, and reuses it on later runs. OpenAI audiences cannot be deleted, and archiving is permanent: an archived audience cannot be restored, targeted, or written to. If the configured audience was archived, enter a new List name and Amperity creates a fresh audience.

Note

An OpenAI custom audience needs roughly 25,000 matched users before it can be used for inclusion targeting or bid adjustment. Below that size it can still be used for exclusion, which has no minimum matched size.

Note

OpenAI custom audiences are not supported for campaigns that target the European Economic Area (EEA) or Switzerland. Confirm your campaigns target other regions before syncing.

Note

If OpenAI rejects a membership batch, Amperity reports that batch’s members as failed rows and stops the run without sending the remaining batches. Re-running is safe: Amperity resubmits each batch so an interrupted change resumes rather than being applied twice.

Get details

Review the following details before configuring credentials for OpenAI Audiences and before configuring Amperity to send audiences to OpenAI Audiences.

	Credential settings API key Required An API key that authorizes Amperity to manage custom audiences for a single OpenAI ad account. OpenAI generates the key as a bearer token, and Amperity adds it to each request automatically. Issue the key from the Settings tab of OpenAI Ads Manager . Each key is scoped to one ad account, and the key itself identifies the account, so no account ID is required. Grant the key Ads Management API access (the default for keys created from the Settings tab). If the key is revoked or regenerated, update the credential in Amperity.
	Required configuration settings Match identifier Required The dataset column OpenAI matches members on. Select one of “email”, “phone”, “email_sha256”, or “phone_number_sha256”. Raw email and phone values are normalized and SHA-256 hashed before sending; the email_sha256 and phone_number_sha256 columns are sent as supplied. A single identifier is used for every member of the audience, and it is also the key Amperity uses to track membership changes across runs, so it cannot be changed without recreating the audience. List name (Required at orchestration) The name of the OpenAI custom audience to create or update. If no audience by that name exists on the account, Amperity creates one. Must be at least 3 characters. Note OpenAI audiences cannot be deleted, and archiving is permanent. If the audience with this name was archived in OpenAI Ads Manager, it cannot be reused — enter a new list name and Amperity creates a fresh audience.
	A query or segment that returns the one column matching the configured Match identifier.

Configure credentials

Configure credentials for OpenAI Audiences before adding a destination.

An individual with access to OpenAI Audiences should use SnapPass to securely share “API key” details with the individual who configures Amperity.

To configure credentials for OpenAI Audiences

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select OpenAI Audiences. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “openai-ads-audiences” credential type, configure settings, and then click Save. API key Required An API key that authorizes Amperity to manage custom audiences for a single OpenAI ad account. OpenAI generates the key as a bearer token, and Amperity adds it to each request automatically. Issue the key from the Settings tab of OpenAI Ads Manager . Each key is scoped to one ad account, and the key itself identifies the account, so no account ID is required. Grant the key Ads Management API access (the default for keys created from the Settings tab). If the key is revoked or regenerated, update the credential in Amperity.

Add destination

Use a sandbox to configure a destination for OpenAI Audiences. Before promoting your changes, send a sample audience, and then verify the results in OpenAI Audiences. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for OpenAI Audiences

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for OpenAI Audiences, do one of the following: Click the row in which OpenAI Audiences is located. Destinations list alphabetically and you can scroll up and down the list. Search for OpenAI Audiences. Start typing “openai”. The list filters to show only matching destinations. Select “OpenAI Audiences”.
	Select the credential for OpenAI Audiences from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Match identifier The dataset column OpenAI matches members on. Select one of “email”, “phone”, “email_sha256”, or “phone_number_sha256”. Raw email and phone values are normalized and SHA-256 hashed before sending; the email_sha256 and phone_number_sha256 columns are sent as supplied. A single identifier is used for every member of the audience, and it is also the key Amperity uses to track membership changes across runs, so it cannot be changed without recreating the audience. List name (Required at orchestration) The name of the OpenAI custom audience to create or update. If no audience by that name exists on the account, Amperity creates one. Must be at least 3 characters. Note OpenAI audiences cannot be deleted, and archiving is permanent. If the audience with this name was archived in OpenAI Ads Manager, it cannot be reused — enter a new list name and Amperity creates a fresh audience.
	After configuring this destination users may use: Orchestrations to send query results Orchestrations and campaigns to send audiences Orchestrations and campaigns to send events
	Validate the audience with OpenAI Audiences by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by OpenAI Audiences. Send the sample audience to OpenAI Audiences and verify the sample audience is correct in OpenAI Audiences. Make adjustments if necessary. Only send full audiences after validation is complete.