Custom Audiences
Overview
There are multiple ways for partners to create Custom Audiences. Please note that you cannot exclude lookalike custom audiences from targeting. Additionally, you cannot target both a custom audience and a custom audience lookalike on the same ad line item (ad group). Audience management Audiences can be managed via audience partners and Ads API partners. We offer a series of endpoints in the API to access and maintain custom audiences. For custom audience information, we offer 2 endpoints:- GET accounts/:account_id/custom_audiences
- GET accounts/:account_id/custom_audiences/:custom_audience_id




Audiences FAQ
Q: We pushed a huge amount of data, why does the audience size show up as TOO_SMALL? A: Currently the data is being added into audience in realtime, but the job which processes data to provide audience size will run only after a period of time. The correct audience size should be displayed in the UI after a matter of hours. Q: We finished sending audience data, and waited 24 hours or more, but still cannot target the audience - what should we do as next steps? A: Please confirm that the following things:- The user ID being passed is correct and not malformed.
- The audience names being passed are correct and match previous membership updates.
- Please confirm the response from POST commands.
- Please confirm the ID Sync pixel is implemented correctly, and as described by ID Sync process enough users have visited the site in question to map users. Unmapped users in the membership updates will not be translated into targeted users.
- The minimum size for an audience to is 100 users (post match). If an audience with less than 500 users is matched, it will not be available for targeting in the X Ads UI.
- It typically takes 4-6 hours to process the audience files, but that will depend on the size of the file. Once the file is processed the audiences are available on the X Ads UI.
- Match Rate = 90 day active X users / number of users provided
- You can provide a test audience file and use “keltonlynn” as the advertiser handle. We can then verify that the file is able to be properly ingested and loaded into the X UI.
p_user_id
)?
- This is the identifier that is used by your company to uniquely identify each of your customers.
- This can be an email address, device ID, X @handle or ID).
- This will be provided by an encrypted email. Please provide your public PGP key to mpp-inquiry@x.com and we will send you a test email to verify that everything is working. Once verified, we will send you the HMAC Key.
- X will provide a test file (containing sample email addresses, device IDs, etc…) and a resulting hash file that you can verify your results against.
- No, there is no size limitation for the full data match file.
- Once the file is received by X, it will take approximately 1 day to process the file.
CRM

Partner ID Matching Requirements
If company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, X user ID, etc…) then this is the recommended process. 1. Full Data match Initially, Company will provide a comprehensive list of all user records which include a unique common user identifier with X in a single file to perform a full data match and produce a mapping stored by X of Partner IDs (p_user_id
) to X IDs (tw_id
). This will be done on a 2-3 month basis regularly to ensure proper upkeep. Once the match is completed, X will share a baseline match rate from this file with Company via e-mail.
The format of this file should be:
Name Convention: FullDataMatch.[CompanyName].txt
Hashing Algorithm: HMAC_SHA-256
Format:
Column 1: HMAC hashed value of common identifiers
Column 2: Partner User ID (unique per user, non-unique in file)
Column Delimiter (CSV): Commas will be used to delimit the hashed common user identifier from the Partner ID
Line separated values
- Ex: If user record A has Partner User ID 1 and common identifier 1, 2 and 3:
common user identifier 1 | p_user_1 |
common user identifier 2 | p_user_1 |
common user identifier 3 | p_user_1 |
p_user_id
to create custom audiences for customers for targeting on X.
- Line separated values
p_user_id
-
- (Same as provided in 1. Full Data Match section above. If the value provided in full data match is hashed then Company will provide same hashed value in audience file. If value provided is not hashed then Company will provide unhashed value.)
Standard Matching Requirements
If company does not use a standard ID for mapping of all customer user identifiers, this is the recommended process. Custom Segment Lists Company will provide lists of hashed common user identifiers directly to X on behalf of customers to to create custom audiences. The format of this file should be:- Line separated values
- Hashed common user identifier (i.e. e-mail address)
- Follow file naming conventions outlined below
- Follow hashing directions for e-mail addresses below (in Hashing Directions)
Custom Segment List File Naming & Operations
The operation of a file will be dictated by the name of the file with the following available operations and general file naming convention: audiencename_partnername.handle.operation.filetype- audiencename: The name of the Custom Audience. This field is the name that will be displayed when selecting the audience in the ads.x.com campaign setup UI e.g. brand_loyalty_card_holders.
- partnername: Name of the company delivering the data on behalf of advertiser e.g. company_name.
- handle: X Account (@handle) that will have access to Custom Audiences e.g. @pepsi, @dietpepsi
- operation: new, add, remove, removeall, replace (details below)
- : Standard Unix epoch time in seconds, used to ensure that each audience file uploaded is unique
- filetype: file should be in *.txt format
Creating and Updating Audiences
Create a new audience with a single file e.g. loyalty_card_holders_partnername.pepsi.new.txt Add - Add the matches from a list to an existing audience e.g. loyalty_card_holders_partnername.pepsi.add..txt Remove - Remove the matches from a list from an existing audience Ex: loyalty_card_holders_partnername.pepsi.remove..txt Remove All - Remove the matches produced from a regularly updated cumulative list from all audiences for that client (i.e. Client’s Opt Out List). Ex: partnername.pepsi.removeall.txt- This can be used for a comprehensive list of users who have opted-out from the Advertiser.
- X will only respect the latest list provided in this file, and will respect across all existing and future audiences for matched.
Hashing Directions
X will securely share a base64 encoded production key via PGP for hashing common user identifiers (i.e. email addresses). Company will base64 decode the key to produce a 32-byte key to be used to perform the hashing. Example base64 encoded key: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= Example Base64 decoded key: /:� TшY Normalization: Company will perform basic normalization on the common user identifiers before hashing (except on Device IDs, see Device ID Normalization section).E-mail Normalization
Namely, strip out the leading and trailing spaces and also lowercase the email address. Ex: Raw e-mail address: testemail_Organisational_baseball+884@
It92I6Ev2B.
Com
After normalization: testemail_organisational_baseball+884@
it92i6ev2b.
com
Hashed value: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec
Note: The specific number of characters for both the encoded hmac and key could vary based on the input and the encoding so the specific number of characters.
Device ID Normalization
We will have the same requirements for hashing of device IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. We strip out spaces like we do with email addresses, but there is no lowercase normalization for IDFAs/Android IDs and the exact format of the IDFA/Android ID should be used. Here is example raw format of Device IDs for iOS & Android, pre-hashing: iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4X User ID Normalization
X IDs will still be hashed as the grouping of data - ie Customer List of @handles - is private to the advertiser even though it is not PII. We will have the same requirements for hashing of X IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. Spaces should be stripped out of both the X ID/@
username, but User IDs do not require normalization. @usernames should be lowercased for normalization. And the @ symbol should not be included as part of the username.
The raw ID format will be:
- User ID: 27674040
- @username: testusername
ID Sync Integration
Partners sending data with ap_id
must undergo an ID Sync process to generate a mapping of the advertiser or partner’s user ids to X user ids. This allows advertisers to directly target their own user segments on X. Partners must also set the value of the param user_identifier_type
to either TALIST_PARTNER_USER_ID
or TAWEB_PARTNER_USER_ID
while sending their membership updates.
- Web Only: This can be done by placing a pixel on the advertiser’s site, as outlined below.
- List: This can be done using any of the methods described on the CRM page.
Pixel URL
Base URL |
https://analytics.x.com/i/adsct |
Pixel Parameters
Parameter | Description |
p_id | Your X-assigned partner id |
p_user_id | The user’s id in the partner system |
ID Sync Pixel:
Using an example partner id of 111, and an examplep_user_id
of abc, the constructed pixel would be the following:
Column Number | Column Name | Column Type | Description |
1 | Partner ID | string | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner. |
2 | The user’s id in the partner system | string | The p_user_id is the unique ID that is used to identify the user by the Partner. The file containing these opt-out users should be uploaded using the TON upload endpoint and the path of uploaded data should be sent to the Global Opt Out endpoint here:PUT accounts/:account_id/custom_audiences/global_opt_out. |
p_id
must set the user_identifier_type
to TALIST_PARTNER_USER_ID
or TAWEB_PARTNER_USER_ID
.
All other steps will remain the same as those listed in the Real-Time Audience API Integration Guide
Custom Audiences User Data
This document outlines the format for [Custom Audience]/x-ads-api/audiences user data. Data normalization Device IDs:- IDFA - lower-cased with dashes; ex:
4b61639e-47cc-4056-a16a-c8217e029462
- AdID - original format on device is required, not capitalized with dashes; ex:
2f5f5391-3e45-4d02-b645-4575a08f86e
- Android id - original format on device is required, not capitalized without dashes or spaces; ex:
af3802a465767e36
- lowercase, remove leading and trailing spaces; ex:
support@x.com
- no @, lowercased and leading and trailing spaces trimmed; ex:
jack
- Standard integer; ex:
143567
SHA256
, without a salt. Additionally, the final output hash must be in lower case. E.g., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and **not **49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D
Custom Audiences: Web

p_user_ids
) to target on behalf of an advertiser. This is accomplished through an ID Sync process that builds a mapping between the p_user_ids
and X user ID. This mapping is then used to produce lists of X User IDs that can be used for Targeting. These custom audiences will be made available on the advertiser’s specific @handle specified by the label on ads.x.com Custom Audiences Web campaign setup.
X will provide the secure pixel that can be dropped on partner tags and sites in order to match the IDs (p_user_ids
) to X user IDs. Once the ID Sync process is complete, the targeting files will be created by the partner and will be made available to X through a HTTPS endpoint. These targeting files are ingested on a regular basis by X and are then made available in the X UI.
X Secure Pixel
The X secure pixel will look as follows:
https://analytics.x.com/i/adsct?p\_user\_id=xyz&p_id=123
p_user_id
- xyz represents the partner user ID that is provided by the Partner
p_id
- 123 represents the unique ID for the Partner (provided by X)
Partner HTTPS Endpoint & Targeting User File
Partner will need to provide X with a HTTPS endpoint and credentials (username/password) that can be used to ingest the targeting file on a regular basis. A sample HTTPS endpoint will look as follows:
- Partner Targeting User File
- Targeting Conversion File
- 199.16.156.0/22
- 199.59.148.0/22
Column Number | Column Name | Column Type | Description |
---|---|---|---|
1 | partner id | string | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner. |
2 | advertiser id | string | The “advertiser id” is the @handle for the advertiser. |
3 | p_user_id | string | The “p_user_id” is the unique ID that is used to identify the user by the Partner. |
3 | confidence score | integer | The “confidence score” is optional. Our recommendation for confidence score is to use 0-100. If the use case is for retargeting, then a confidence score of “100” is a user who has been directly retargeted. Any score from 0-99 would correspond to the level of confidence of the look-alike. |
4 | segment label | string | The “segment label” is optional. Partners can use “segment label” to specify product categories, for example. Our recommendation is to use this “segment label” as this is the human readable name for Custom Audiences in the ads.x.com UI. |
Audience API Integration
Overview
The Audience API was launched as part of v4 of the Ads API and with it, brings several improvements to the legacy Audiences endpoints. This new endpoint is backed by a new Audience processing backend, and brings several improvements in terms of stability, robustness and reliability. The purpose of this guide is to highlight the differences between the Audience API and the legacy Audience upload and management processes. Reference documentation can be found on the Audience API reference documentation page. Note: All Audience user data must be SHA-256 hashed prior to upload. More details, along with the accepted user identifier types and data normalization can be found on the user data page. Changes to Audience Functionality The following changes to Custom Audiences have been introduced as of v4 and any deprecated endpoints will no longer be available once v3 of the Ads API has been sunset:- Deprecated TON Upload:
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
- Deprecated Real Time Audiences:
- POST custom_audience_memberships
- Custom Audience:
- The
list_type
parameter will be removed from the request and response on all Custom Audience endpoints. This parameter was previously used to identify the user identifier type of the Audience (i.e., email, X User ID, etc.) however Audiences now have the ability to accept multiple user identifiers for the same Audience thereby making this value irrelevant.
- The
- General:
- The Audience lookback window has been updated to match against users active within the past 90 days (from 30 days)
- The minimum number of matched users required for an audience to be targetable has been decreased to 100 users (from 500 users)
Prerequisites
- Ads API access
- For access to the Audience endpoint, you will need to be added to an allowlist. Please fill this form and accept the new X Ads Products and Services Agreement if initially accepted prior to 2018-08-01
Step in Process | Audience API | (Deprecated) TON Upload |
---|---|---|
Create a shell Audience | Can be created via the [POST custom_audience endpoint]/x-ads-api/audiences | Can be created via the [POST custom_audience endpoint]/x-ads-api/audiences |
Add a new user | Use the operation_type Update with the Audience endpoint | Use the operation ADD with the POST custom_audience_changes endpoint |
Remove a user | Use the operation_type Delete with the Audience endpoint | Use the operation REMOVE with the POST custom_audience_changes endpoint |
Opting-Out Users | Use the operation_type Delete with the Audience endpoint and the corresponding custom_audience_id s that the user is a part of | Use the Global opt-out endpoint |
Create a new Custom Audience
Create a new Custom Audience “shell” using the [POST custom_audience]/x-ads-api/audiences endpoint and retrieve the corresponding Custom Audienceid
. This step is required if creating an Audience from scratch. If updating an existing Audience, skip to the next section
Add Users to an Audience
Use the POST accounts/:account_id/custom_audiences/:custom_audience_id/users with the Custom Audienceid
and a sample payload like so:
POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users
operation_type
Update
. The new Audience interface enables the ability to pass in multiple user keys for a single user. Each object in the array of JSON objects corresponds to a single user. Using the example payload above, the request will add two users to an Audience, one with an email
and handle
and another with an email
and twitter_id
.
Remove Users from an Audience
Similar to the process outlined for adding users, users can be removed from an audience using like so: POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/usersoperation_type
must be set to Delete
and users will be matched on any keys that were present when adding users to the audience. For example, if a user was added to an audience using an email
and twitter_id
, then the same user can be removed using any one of these keys, i.e., either email
or twitter_id
or both.
Additionally, it is possible to add and remove users from an Audience within the same request. The endpoint supports multiple operation_type
per request.
Opt-Out Users
With the deprecation of the global opt-out endpoint, partners are required toDelete
any users that have opted-out of any Audiences. There are a few ways to achieve this:
- Keep track of which users are part of which Audiences and remove these users individually from each Audience.
- Remove the user from all Audiences associated with an Ads account.
- We strongly recommend calling this endpoint in near real-time batches to avoid spiky queues which take longer to process and in general cause unnecessary load on our system. This also ensures users are available for campaign targeting sooner.
- A successful API call will return a
success_count
andtotal_count
corresponding to the number ofuser
objects that have been received in the request. - This endpoint is atomic in nature, that is, either the entire request is successful or in case of any errors then the entire request will fail. In case of an error response, consumers of the API are recommended to fix the error and retry the request with the entire payload.
- Upon failure, partners recommended to use an exponential backoff approach with retries. For example, retry immediately upon the first failure, retry after 1 minute after the second failure and retry after 5 minutes after the third consecutive failure, and so on
API Reference
Keyword Insights
GET insights/keywords/search
Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords. A maximum time range (end_time
- start_time
) of 7 days is allowed.
Please note that results are scoped by a single geo (country).
Resource URL
https://ads-api.x.com/12/insights/keywords/search
Parameters
Name | Description |
---|---|
granularity required | Specifies the granularity of the data returned for the time range denoted by start_time and end_time . For instance, when set to HOUR , you will be presented with a datapoint for each hour between start_time and end_time . request.Type: enum Possible values: DAY , HOUR |
keywords required | A comma-separated string of keywords to narrow search by. All keywords are OR’ed with one another. Note: A maximum of 10 keywords ( keywords and negative_keywords combined) may be used.Type: string Example: developers |
start_time required | Scopes the retrieved data to data collected in the window of time between start_time and end_time . Expressed in ISO 8601.Type: string Example: 2017-07-10T00:00:00Z |
end_time optional | Scopes the retrieved data to data collected in the window of time between start_time and end_time . Expressed in ISO 8601.Note: Defaults to the current time. Type: string Example: 2017-07-11T00:00:00Z |
location optional | A targeting value you would get from the GET targeting_criteria/locations endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported. Type: string Example: 0ce8b9a7b2742f7e |
negative_keywords optional | A comma-separated string of keywords to exclude. All negative keywords are OR’ed with one another. Note: A maximum of 10 keywords ( keywords and negative_keywords combined) may be used.Type: string Example: rain |
Tailored Audience Permissions
GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions
Retrieve details for some or all permissions associated with the specified tailored audience. Resource URLhttps://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
tailored_audience_id required | A reference to the tailored audience you are operating with in the request. Type: string Example: 1nmth |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
granted_account_ids optional | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 18ce54aymz3 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
tailored_audience_permission_ids optional | Scope the response to just the desired tailored audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: ri |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions
Example Response
POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions
Create a new permission object allowing the specified audience to be shared with a given account. Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at theis_owner
response attribute in the response for a given audience.
Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS
account feature.
Resource URL
https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
granted_account_id required | The account you wish to grant the tailored audience permissions for. Type: string Example: 18ce54aymz3 |
permission_level required | The type of access to the tailored audience that the granted_account_id should have.Type: enum Possible values: READ_ONLY , READ_WRITE |
tailored_audience_id required | A reference to the tailored audience you are operating with in the request. Type: string Example: 2906h |
POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY
Example Response
DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id
Revoke the specified Tailored Audience sharing permission. Note: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at theis_owner
response attribute in the response for a given audience.
When revoked, we guarantee that the granted account (granted_account_id
) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked.
Resource URL
https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
tailored_audience_id required | A reference to the tailored audience you are operating with in the request. Type: string Example: 1nmth |
tailored_audience_permission_id required | A reference to the tailored audience permission you are operating with in the request. Type: string Example: ri |
DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri
Example Response
Targeted Audiences
GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted
Retrieve a list of active or all line items and campaigns that target a givencustom_audience_id
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 2906h |
with_active optional | When false , includes line items that have servable=false statusType: boolean Default: true Possible values: true , false |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted
Example Response
Custom Audiences Users
POST accounts/:account_id/custom_audiences/:custom_audience_id/users
This endpoint will allow partners to add, update and remove users from a givencustom_audience_id
. The endpoint will also accept multiple user identifier types per user as well.
All data being provided in the users
field of the request except partner_user_id
must be hashed using SHA256
and normalized.
Batch Requests
- The current maximum batch size is
2500
for this endpoint. The batch size is determined by the number of operations (Update
/Delete
) per request. For example, over 2500 operation objects ({"operation_type": "Update/Delete", [..] }
) in one array result in an error. - The max request POST body size this endpoint can accept is
5,000,000
bytes. - The rate limits for this endpoint are 1500 per 1 minute window
- All parameters are sent in the request body and a
Content-Type
ofapplication/json
is required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
success_count
and a total_count
. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is not equal the success_count
and total_count
should be treated as an error condition, requiring a retry.
Batch Errors
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errors
object. - Item-level errors (eg. missing required parameters) are show in the response under the
operation_errors
object. - The index of the error in the
operation_errors
refers to the index in the input item, with the corresponding error message
Resource URL
https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users
Parameters
Name | Description |
---|---|
operation_type required | The per users group operation type being performed.Type: enum Possible values: Update , Delete |
params required | A JSON object containing the users array, the effective_at and expires_at timestamps.Type: JSON |
users required | An array of JSON objects containing all params for an individual user. Type: JSON |
effective_at optional | The UTC time at which the custom audience association(s) should take effect. Expressed in ISO 8601. Defaults to the current date and time. Type: string Example: 2017-07-05T07:00:00Z |
expires_at optional | The UTC time at which the custom audience association(s) should expire. The specified time must be later than the value of effective_at . Expressed in ISO 8601. Defaults to 13 months from the request timestamp.Type: string Example: 2017-07-05T07:00:00Z |
users
object, each element of this object is documented below:
Name | Description |
---|---|
email optional | Email address(es) for the user. Type: Array[String] |
device_id optional | IDFA/AdID/Android ID Type: Array[String] |
handle optional | The @handle(s) belonging to the user Type: Array[String] |
twitter_id optional | The X ID belonging to the user Type: Array[String] |
phone_number optional | Phone number(s) for the user Type: Array[String] |
partner_user_id optional | The user’s ID in the partners’ system. Type: Array[String] |
Example Request
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users
Example Response
Custom Audience Permissions
GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions
Retrieve details for some or all permissions associated with the specified custom audience. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 1nmth |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
granted_account_ids optional | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 18ce54aymz3 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
custom_audience_permission_ids optional | Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: ri |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions
Example Response
POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions
Create a new permission object allowing the specified audience to be shared with a given account. Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at theis_owner
response attribute in the response for a given audience.
Note: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the SHARE_AUDIENCE_OUTSIDE_BUSINESS
account feature.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
granted_account_id required | The account you wish to grant the custom audience permissions for. Type: string Example: 18ce54aymz3 |
permission_level required | The type of access to the custom audience that the granted_account_id should have.Type: enum Possible values: READ_ONLY , READ_WRITE |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 2906h |
DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id
Revoke the specified Custom Audience sharing permission. Note: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at theis_owner
response attribute in the response for a given audience.
When revoked, we guarantee that the granted account (granted_account_id
) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 1nmth |
custom_audience_permission_id required | A reference to the custom audience permission you are operating with in the request. Type: string Example: ri |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri
Example Response
Custom Audiences
GET accounts/:account_id/custom_audiences
Retrieve details for some or all Custom Audiences associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
count optional | Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1 , 1000 |
cursor optional | Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow |
permission_scope optional | Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own. Type: enum Default: OWNER Possible values: OWNER , SHARED |
q optional | An optional query to scope resource by name .Note: This performs case-insensitive prefix matching. Type: string Min, Max length: 1 , 255 |
sort_by optional | Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc |
custom_audience_ids optional | Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 1nmth |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
with_total_count optional | Include the total_count response attribute.Note: This parameter and cursor are exclusive.Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth
Example Response
GET accounts/:account_id/custom_audiences/:custom_audience_id
Retrieve specific Custom Audiences associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 2906h |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h
Example Response
POST accounts/:account_id/custom_audiences
Create a new placeholder Custom Audience associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
name required | The display name for this audience. Unique name value must be used. Failure to do so will result in an error. Type: string Example: ads api users |
description optional | A description for this audience. Type: string Example: Collection of all users of the Ads API |
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers
Example Response
PUT accounts/:account_id/custom_audiences/:custom_audience_id
Update the specfic Custom Audience associated with the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the Custom Audience you are operating with in the request Type: string Example: 2906h |
name optional | The display name for this audience. Unique name value must be used. Failure to do so will result in an error. Type: string Example: ads api users |
description optional | A description for this audience. Type: string Example: Collection of all users of the Ads API |
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed
Example Response
POST batch/accounts/:account_id/custom_audiences
Allows for batch creation of Custom Audiences. See the Custom Audiences Overview page for information on audiences. Note: This batch endpoint is currently in closed beta and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created. Batch Requests- The current maximum batch size is 10.
- All parameters are sent in the request body and a
Content-Type
ofapplication/json
is required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errors
object. - Item-level errors (eg. missing required parameter) are shown in the response under the
operation_errors
object.
- Flexible Audiences are immutable once created.
- Custom Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences
- A maximum of 10 Custom Audiences leaf nodes can be used to create a Flexible Audience.
https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
audience_type required | The type of audience to create. Type: enum Possible values: FLEXIBLE , MOBILE_AUDIENCE |
child_segments required | An array containing objects which define the subset of a Custom Audience’s members that you would like to target. Each object should contain a custom_audience_id , frequency , frequency_comparator , lookback_window , negate , and, in some cases, additional child_segments .Type: array |
name required | The display name for the audience. Unique name value must be used. Failure to do so will result in an error. Type: string Example: my_flexible_audience_name |
operation_type required | The per item operation type being performed. Type: enum Possible values: Create , Update , Delete |
boolean_operator sometimes required | The logical relationship between the child segments in its parent (containing) object. Required if child_segments is non-empty for the parent object. Type: enum Possible values: AND , OR |
lookback_window sometimes required | An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience. Type: int Possible values: 1 , 7 , 14 , 30 |
segments sometimes required | An object containing a boolean_operator and child_segments which define the subset of a Custom Audience’s members that you would like to target.Type: object |
custom_audience_id sometimes required | The id of the custom audience to use as a child segment. Type: string Example: tyfo |
frequency optional | An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given custom audience. Type: int Default value: 1 |
frequency_comparator optional | The comparator to the frequency passed in the request.Note: In the values below, GTE refers to greater than or equal, LT to less than, and so on.Type: string Possible values: NUM_GTE , NUM_GT , NUM_EQ , NUM_LTE , NUM_LT Default value: NUM_GTE |
negate optional | Negates the segment and thus is excluded in the combination. Type: boolean Default value: true Possible values: true , false |
POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences
DELETE accounts/:account_id/custom_audiences/:custom_audience_id
Delete the specified Custom Audience belonging to the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
custom_audience_id required | A reference to the custom audience you are operating with in the request. Type: string Example: 2906h |
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h
Example Response
Do Not Reach Lists
GET accounts/:account_id/do_not_reach_lists
Retrieve details for some or all Do Not Reach List associated with the current account. Note: Anaccount_id
can only have at most one Do Not Reach List
Resource URL
https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
with_deleted optional | Include deleted results in your request. Type: boolean Default: false Possible values: true , false |
GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists
Example Response
POST accounts/:account_id/do_not_reach_lists
Create a new Do Not Reach List associated with the current account. Note: Anaccount_id
can only have at most one Do Not Reach List
Resource URL
https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
description optional | A description for this audience. Type: string Example: A list of users to exclude |
POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude
Example Response
POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users
This endpoint allows users to be added, updated and removed from a givendo_not_reach_list_id
. This endpoint only accepts emails as the valid user identifier type.
All data being provided in the emails
field of the request must be hashed using SHA256
and normalized.
Notes
- An
account_id
can only have at most one Do Not Reach List - Users added to this list must have an
expires_at
timestamp set to less than 13 months from the current timestamp - Do Not Reach List API does not accept an
effective_at
timestamp and defaults to the current timestamp - Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account
- The current maximum batch size is
2500
for this endpoint. The batch size is determined by the number of operations (Update
/Delete
) per request. For example, over 2500 operation objects ({"operation_type": "Update/Delete", [..] }
) in one array result in an error. - The max request POST body size this endpoint can accept is
5,000,000
bytes. - The rate limits for this endpoint are 1500 per 1 minute window
- All parameters are sent in the request body and a
Content-Type
ofapplication/json
is required. - Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.
success_count
and a total_count
. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is not equal the success_count
and total_count
should be treated as an error condition, requiring a retry.
Batch Errors
- Request-level errors (eg. max batch size exceeded) are shown in the response under the
errors
object. - Item-level errors (eg. missing required parameters) are show in the response under the
operation_errors
object. - The index of the error in the
operation_errors
refers to the index in the input item, with the corresponding error message
https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users
Parameters
Name | Description |
---|---|
account_id required | The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t |
do_not_reach_list_id required | A reference to the Do Not Reach List you are operating with in the request Type: string Example: 2906h |
operation_type required | The per users group operation type being performed.Type: enum Possible values: Update , Delete |
params required | A JSON object containing the emails array and expires_at timestamp.Type: JSON |
users required | An array of JSON objects containing all params for an individual user. Type: JSON |
expires_at optional | The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in ISO 8601. Defaults to 13 months from current timestamp. Type: string Example: 2017-07-05T07:00:00Z |
users
object, each element of this object is documented below:
Name | Description |
---|---|
email optional | Email address(es) for the user. Type: Array[String] |
phone_number optional | Phone number(s) for the user Type: Array[String] |
DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id
Delete the specified Do Not Reach List belonging to the current account. Resource URLhttps://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id
Parameters
None
Example Request
DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp
Example Response