User Guides
Send query results to 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.
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.
The steps that are required to send audiences to OpenAI Audiences from Amperity.
Caution
This destination is available for sending query results to OpenAI Audiences after it is configured by a Datagrid Operator or your Amperity representative.
If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to OpenAI Audiences.
Build query¶
Build a query that returns the column matching the Match identifier configured on the destination.
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.
The following example returns email addresses for a destination whose match identifier is email:
SELECT
email
FROM Customer_360
WHERE email IS NOT NULL
Amperity hashes raw email and phone values before sending them; do not hash them in the query. Choose the email_sha256 or phone_number_sha256 match identifier only when your query already returns a correctly normalized SHA-256 digest. A member whose identifier value is missing or cannot be used is dropped and reported as a failed row.
Add orchestration¶
An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.
Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.
From the Object type dropdown, select Query.
From the Object dropdown, select the query for which results is sent to OpenAI Audiences.
From the Destination dropdown, select a destination that is configured for sending data to OpenAI Audiences.
Verify all settings.
Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.
Click Save.
Run orchestration¶
Run the orchestration manually to validate that it works.
Open the Activations page, select the Orchestrations tab, and then open the menu for the OpenAI Audiences orchestration. Select Run.
The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.