Custom Audiences Formatter for X Ads (Twitter)

How to prepare lists for X custom audiences

X custom audiences built from a list can match five kinds of identifiers, and each one has its own format rule on X's List Custom Audiences help page. Phones need E.164 with a plus sign, handles must lose the @, IDFAs must be lowercase. This tool applies those rules to a messy export, sorts each identifier into its own file, and can hash every line with SHA-256 the way X's Ads API documentation describes.

1. Add your list. An event sign-up sheet, a CRM export or a spreadsheet of followers you collected. Use Try sample data to see every check at work.
2. Check the columns. Headers such as Twitter Username, Twitter ID or Device ID are picked up. Profile links like x.com/name are fine in the handle column.
3. Set the default country for phone numbers without a country code. A country column, if you have one, wins.
4. Choose plain or hashed, and the file type. Plain text is the simplest: X hashes it during the upload.
5. Download one file per identifier type. Each has one value per line and no header row.

How each identifier is written

Upload the files in X Ads

1. Open the Audiences page, click Create audience and choose List.
2. Enter an audience name and, if you like, a description.
3. Drag in the first file (or browse to it) and press Next when it shows in the upload box. For a hashed file, tick “The records in this data file are already normalized and hashed using SHA256”.
4. Review the data and set the identifier type for the column, for example Email or Phone number.
5. Keep the browser window open until the upload ends. Add the other files to the same audience later from the drop-down next to it in the Audiences tab — one file at a time.

In a campaign, open the Audiences part of Targeting and choose to include or exclude the list. Only audiences marked “Ready” can be selected.

X custom audience errors and fixes

“One or more pre-hashed records is not in the correct format”

This appears when the hashing checkbox and the file do not agree: a plain file uploaded with the box ticked, or a hashed file without it. X also lists other causes: a file type other than .csv, .tsv or .txt, two identifier types in one column, or gaps and missing rows. Our files avoid all of them.

X custom audience too small

Fewer than 100 active X users matched. Combine smaller lists into one bigger file, add more identifiers per person (an email and a phone and a handle all count), and delete the small audience before you upload the larger one. X's older API FAQ still mentions 500 users; the current help page says 100.

X custom audience phone number format

X asks for E.164: a plus sign, the country code, then the number with no spaces. 06 12 34 56 78 from a French customer becomes +33612345678. Numbers that cannot be real for their country are rejected and listed.

Names, links and broken handles

CRMs often store a full profile link, or a person's name in the “Twitter” field. X wants only the username, without @. The tool pulls ben_sample out of https://x.com/ben_sample?s=20 and jack out of an intent/user?screen_name=jack link. It rejects anything that cannot be a username under X's username rules: names with spaces like “Carla Demo”, dots or dashes, more than 15 characters, emails, and links such as /search or /home.

User IDs destroyed by Excel

X user IDs are long numbers. Excel shows them as 1.45E+18 and keeps only 15 digits, so the real ID is gone. Those rows are rejected: export the IDs again with the column set to Text.

Very large uploads

X suggests splitting files over 4 GB into smaller uploads to stay within your browser's limits. The tool does that split for you.