List Custom Audiences
List Custom Audiences allow advertisers to create Custom Audience segments by uploading lists that contain customer & user data (1P or 3P). Identifiers in a list are matched with @handles on X to create an audience that can be targeted, excluded, or used as a seed for lookalikes.
Create your List Custom Audiences
Once you’ve identified the people that you would like to include in your audience, take the following steps to create your List Custom Audience.
- Create your List file in an accepted format. Supported file formats are .csv, .tsv, and .txt.”
- Add your user identifiers. Supported identifiers include email address, phone number, X @username, user ID, or Mobile Advertising IDs (iOS Advertising Identifiers, Google Advertising IDs, or Android IDs,.The identifiers on your list can be separated by lines or commas. See formatting requirements in the FAQ below.”
- Pre-hash your file. You can choose whether or not you’d like to pre-hash your file before uploading. If you choose to pre-hash your file, please follow these formatting instructions. If you choose not to pre-hash your file, you can skip this step as we will automatically hash the data during the upload process.
- Prepare for upload. Navigate to your “Audiences” manager page under the drop-down “Tools” menu on ads.x.com. On this page, click "Create audience" then select “List” from the “Choose an audience type” pop-up module.
- Add your list. Set an audience name and description (optional) then drag and drop or browse and upload your file via the noted section. Press “Next” when your file appears in the upload box.
- Review & define your data. Once your file has completed an initial upload, you will be asked to review the data and define the type of identifier that is being used for matching. If you are using multiple identifiers, you will be asked to specify the identifier type for each column. For any extraneous columns, select the “Do not upload data” option.
- Wait for upload. Don’t close or minimize the browser window while the file is uploading, and only upload one file at a time. For larger files, make sure that you have a reliable and fast internet connection. If files are over 4GB, we recommend segmenting the list into multiple, smaller uploads to avoid exceeding your brower’s upload limits
After you've uploaded your list, you'll see your new List Audience appear in your Audiences tab as "Processing". Once your audience has matched at least 100 people, the status will change to "Ready" and you will see the “X size” update to reflect the number of people who have been matched.
At this point, your List Audience will be available for selection in the campaign creation form, but it may not be done processing. Lists can take up to 48 hours to finish the matching processing and the “X size” will continue to update until the processing is complete.
Audience showing as too small? Find out why in our FAQ below.
Use your List Custom Audiences
To target or exclude the people on your List Custom Audiences, navigate to the Audiences module within the Targeting section of the campaign form.
Select whether you would like to include or exclude your audience via the drop-down on the left-hand side of the search bar.
- Include: The people in your List Audience will be included in the targeted audience, and they will be eligible to receive the campaign’s ads as long as they meet the location, gender, age, and device targeting criteria.
- Exclude: The people in your List Audience will be excluded from the targeted audience, and they will NOT be eligible to receive the campaign’s ads - even if they meet the other targeting criteria.
After deciding to include or exclude, search or browse to find the specific audience that you want to select. As a reminder, only audiences that are marked the status “Ready” in Audiences manager are eligible to be used in campaigns.
To respect user privacy, the minimum size for a Custom Audience to be usable is 100 X users. If your List Custom Audience is under 100 X users, it will display as "Audience too small" and will not be available for selection.
Once you’ve finished adding your Custom Audiences, complete the remaining campaign setup steps, and launch!
Frequently asked questions
The format of each entry must conform to the following normalization requirements:
Email Address: Text can be any case, remove all spaces (e.g. support@x.com)
Phone Number: Please use e.164 format, remove all spaces (e.g. +16175551212)
X @Handle: Do not include the @, text can be any case, remove all spaces (e.g. jack)
X User ID: Please use standard integers, remove all spaces (e.g. 143567)
Mobile Advertising ID:
- Device ID: IDFA entries must be lower-cased with dashes (e.g. 4b61639e-47cc-4056-a16a-c8217e029462)
- AdID: The original format on the device is required, not capitalized with dashes (e.g. 2f5f5391-3e45-4d02-b645-4575a08f86e)
- Android ID: The original format on the device is required, not capitalized without dashes or spaces (e.g.: af3802a465767e36)
When you create a Custom Audience, there's an initial processing period where the users on the Custom Audience. are "matched" by our systems to their X @handle. This allows us to then serve your Promoted Ads to their accounts.
It's possible that not all of the users on your Custom Audience are active X users, which is why you might see a final Custom Audience size that is smaller than your original uploaded list.
Every Custom Audience is different, and until your list is processed and "matched", we cannot accurately estimate the match rate for an individual advertiser's Custom Audience. Once the Custom Audience is no longer showing as "Processing" in your Audiences tab, the number of matched users for the Custom Audience will be shown. If there were less than 100 active X users matched, it will show as "Audience too small". Unfortunately "too small" Custom Audiences will not be available for targeting in campaigns to respect user privacy.
- Add more user information to your .csv file. Then, delete the "too small" CA from your Audiences Tab and reupload the new, larger CA to reinitiate the matching process.
- Combine two smaller .csv files. Then, delete the "too small" CA from your Audiences Tab and reupload the new, larger CA to reinitiate the matching process.
- Create a .csv file from @handles. Large lists of @handles maximize your chances of matching 100 X users. We recommend files of at least 2000 @handles.
To respect user privacy, your Custom Audience must be at least 100 X users for it to be usable in your campaigns. CA's that fall short of this requirement will say “audience too small” in your Audiences tab, and cannot be used for campaign targeting. Use the tips above to increase your match rate and achieve a larger, usable audience.
When creating a List Custom Audience, the information in your data file is always hashed before it's sent to X, and X never reveals or shares the information in your list with anyone or any other service.
We also offer the option to upload a List that is pre-hashed. If you're pre-hashing your file (optional), please follow these formatting instructions:
- Entries must be line separated, terminated with either LF (\n) or CRLF (\r\n). Supported file formats are CSV (.csv), TSV (.tsv), and TXT (.txt).
- If your file contains more than one identifier type, the identifiers must be split into separate columns. For example, emails in column A, phone numbers in column b. Include one hashed value per line.
- After uploading, select the correct identifier type for each column or “Do not upload” for extraneous columns.
The entry on each line must be hashed using SHA256, without a salt.
This error message appears when your uploaded list is not formatted correctly.
Please check the following:
- Your file is in either .csv, .tsv, or .txt format.
- If your file contains more than one identifier type, the identifiers must be split into separate columns. For example, emails in column A, phone numbers in column b. There is only one hashed value per line.
- Entries must be line separated.
- There are no missing rows of information or gaps in your file.
For non-hashed files, make sure you do NOT check "The records in this data file are already normalized and hashed using SHA256" box during upload.
For pre-hashed files, make sure you DO check "The records in this data file are already normalized and hashed using SHA256" box during upload.
First, establish a relationship with one of X’s partners. Many ad partners can manage audiences via API. If you want to create a List audience through a partner using email addresses, leverage our MACT partners and/or ads API partners.
Your ads partner will prepare the Custom Audiences you want to target and send them to X through end-to-end integration. Then X will run a match to determine the audience you can reach on X. You cannot re-upload third-party lists that you do not own.
Please note that your audiences will not include X users that have opted out of receiving interest-based advertising.
You can upload multiple files for the same Custom Audience, and add to audiences that you have already created. The option to upload additional files will appear as an in-line drop-down option for each list Custom Audience in your Audiences tab.
People who have Ads Personalization turned off in their X settings are ineligible to be matched in any Custom Audience. If a person does not want to be matched in any audience, we recommend that they verify that this setting is turned off or disabled.
Ready to get started?
