This guide will walk you through creating, uploading, validating, and managing your custom audience using a simple CSV file.
What is a Contacts List Upload?
Contacts List Upload lets you build custom targeting segments by uploading your own CRM contact lists directly into the platform. This is especially useful if:
You manage your own first-party data.
You want to retarget previous customers.
You want to reach specific leads or segmented profiles from your own database.
Once uploaded, your data is processed securely and becomes available in campaign targeting.
Where to Create a Contacts List
You can start a Contacts List upload from two places:
From the Audiences page (Audiences tab in the header)
From a campaign strategy: in the campaign creation experience, open the Custom & Web Audiences block on a strategy and click Add audience.
A slideover opens with a list of options including CRM integrations. Select Contacts List.
The advertiser is pre-selected, and the new audience is immediately available in the current strategy once created.
Step-by-Step: Creating a Contacts List
1. Start From the Audiences Page
Go to the Audiences section of the platform.
Click the "Create audience" button.
A drawer will open — here you'll choose your audience source.
Select Contacts List to begin.
Choose the advertiser the audience will belong to.
2. Enter Audience Details & Upload Your Files
This is the main setup step where you'll:
Name your audience
Your audience name must be no longer than 100 characters. We recommend using a unique, descriptive name to avoid confusion, though the platform does not currently block duplicate names.Upload your CRM file
ℹ️ Note: At this step, you'll find a button to download the CSV template directly in the platform to help you format your data correctly. The template includes the following columns: email, phone, firstName, lastName, postalAddress, city, zipCode, state, device_id
These columns must be included in the file even if some rows don't populate all fields. Every row must contain at least one valid identifier - a valid email address or a valid device ID (device_id). We recommend including as much additional data as possible per row for better match rates.
Use the drag-and-drop box or click to browse for your file.
We only accept .CSV files, and you can upload one file at a time.
An audience must contain at least 5,000 valid entries and cannot exceed 800,000 valid entries.
3. Save your Audience
Once your audience name is valid and you've uploaded at least one valid file:
The Save button becomes active.
Click Save to complete the process.
File Requirements & Validation Rules
To make sure your CRM audience is uploaded successfully, your CSV file must meet the following requirements:
File type must be .CSV
We only support.csvfiles — other formats like.xlsor.txtwon't work.Required headers must be included
Your file needs to follow the expected structure. Make sure you use our CSV template to avoid formatting issues.The file must not be empty
Files with no data or only empty rows will be rejected.Every row must contain a valid identifier
Each row must include a valid email address or a valid device ID. Rows that have neither will be rejected.Every row must be valid
If any row is invalid, the entire file is rejected. A row is valid when it contains one of these two identifiers:A valid email (e.g., [email protected]) - plain-text or SHA-256 hashed, or
A valid device ID - in standard UUID format, or its 64-character SHA-256 hash
Formatting Guidelines (Per Field)
Field | Format / Rules |
| Must be a valid email (e.g., [email protected]), plain-text or SHA-256 - required on any row that has no device ID |
| A Google Advertising ID (GAID) or Apple IDFA in standard UUID format (e.g., 38400000-8cf0-11bd-b23e-10b96e40000d), or a 64-character SHA-256 hash - required on any row that has no email |
| US phone in international format (e.g., +1 310-555-1234) |
| Must be a 5-digit or 9-digit (ZIP+4) US ZIP code (e.g., 90210 or 90210-1234) |
| Must be a 2-letter US state code (e.g., CA, NY) |
| Free text (no specific format required, but must be non-empty if used in matching logic) |
If your file doesn't meet one or more of these requirements, we'll show you clear error messages to help you fix the issue and try again.
Managing Your Audiences
The Audiences page lists every audience you've created. To view or edit one:
Click Manage below the audience name in the Name column. A panel opens with a summary of that audience: its source, its matched audience size, and any strategies currently using it.
In the Source tile, click the settings icon (⚙️) to open the editor.
Update the audience, then click Continue to save your changes.
In the editor you can:
Rename the audience — edit the Audience name field.
Upload a new list — drag and drop a CSV, or click Browse your file. Already-uploaded files are listed on the right with their entry count and upload date. Use Download template if you need the expected format.
To delete an audience, click Remove at the bottom of the summary panel. Removing an audience can't be undone, so check the active strategies count first — if any strategies are using it, they'll be affected.
⚠️ Audiences used in a published campaign cannot be deleted. The Remove button will be disabled in that case.
Using Audiences in Campaign Setup
During campaign setup, open the Custom & Web Audiences block of the Audience module.
If you haven't created an audience yet
The section shows an empty state and a button to Add audience which opens the New audience panel described before.
Once you have audiences
The section lists all your audiences, each labeled with its source and current size. Use the search field to find one by name, or the All sources dropdown to filter by source type.
An audience showing Counting members instead of a number is still being processed. Its size will appear once matching finishes.
Select the audiences you want to use, then add them to:
Included audiences — the people you want to reach.
Excluded audiences — the people you want to keep out of this campaign, such as existing customers.
Click Reset to clear your selections and start over.
Note: the block starts in Controls mode: Vibe reaches only the audiences you include and keeps out the ones you exclude. On Awareness, Traffic, Leads and Sales campaigns you can switch it to Suggestions with the Manage button. Your included audiences then guide the bidder without limiting reach, and you can no longer exclude audiences. See related article.
Where to See Performance
You can track results of your audience directly in your campaign reports.
Data appears in the Custom Audiences reporting sub-section.
You'll be able to see audience names, but you won't be able to filter by audience source.
If you need help with formatting your file or understanding an error message, reach out to our support team.
Troubleshooting: Why Was My File Rejected?
Our uploader checks every row in your file. If even one row is invalid, the whole file is rejected, and the error message won't tell you which row caused it. Almost every rejected upload comes down to one of the causes below.
🔒 A note on privacy: Contacts lists contain personal information, so our team can't accept, open, or edit your file by email, chat, or any other channel. Everything below can be done on your side. The AI prompt at the end of this section will find most issues in a few minutes.
Start with your error message
Error message | What it usually means | How to fix it |
Missing required headers | A column header is missing or misspelled, or you're using an older template. It can also mean a hidden character was added to the first or last header when you saved the file. | Download a fresh template from the upload screen and keep all 9 headers, even the columns you don't use. Then re-save the file as described in "Hidden characters" below. |
Missing or invalid identifiers | At least one row doesn't have a valid email or a valid device ID. | Go through the row checklist below. |
Too few or too many entries | The file has fewer than 5,000 or more than 800,000 valid entries. | For larger lists, split the file into parts of up to 800,000 rows and upload them one at a time to the same audience. |
An error occurred while uploading your file | A general upload error. | Try the upload again. If it keeps failing, work through the checklists below and then contact support. |
Row checklist
Look for these in your file:
Blank rows. Check especially at the bottom of the file and anywhere rows were copied or pasted. Delete them.
Empty email cells. Every row needs an email, unless it has a device ID instead.
Extra spaces before or after the email. These are invisible in a spreadsheet. Run =TRIM() on the email column to remove them.
Typos, such as a dot right after the
@([email protected]), two dots in a row ([email protected]), two@signs, a missing@, or .con instead of .com.Spreadsheet errors in place of an email, such as
#NAME?,#N/A, or#VALUE!.More than one email in a cell, separated by a comma or semicolon. Put each email on its own row.
Accented or non-Latin characters, such as é, ñ, or ü.
Domains that start or end with a hyphen, such as [email protected].
Hashed emails in the wrong format. Only SHA-256 hashes work, and each one must be exactly 64 characters. MD5 (32 characters), SHA-1 (40 characters), salted hashes, and hashes with a prefix are all rejected.
Invalid values in device_id. If a row has no email, its device ID must be a valid UUID or a 64-character SHA-256 hash. If you don't have device IDs, leave the column empty.
Duplicate rows won't cause an error.
Hidden characters (the most common "everything looks right" issue)
Some ways of saving a CSV add characters you can't see. Our uploader then can't read your headers, so it shows "Missing required headers" even when you used our template.
Excel on Windows: saving as CSV UTF-8 adds a hidden character to the start of the file, which breaks the first header (email).
Excel on Mac: saving as CSV UTF-8 adds hidden characters to the end of each line, which breaks the last header (device_id).
To avoid both, use one of these options:
In Excel: go to File > Save As and choose CSV (Comma delimited), not CSV UTF-8.
In Google Sheets: go to File > Download > Comma Separated Values (.csv).
If you cleaned the file with an AI tool, upload the file it gives you directly. Opening and saving it in Excel again can bring the hidden characters back.
Check your file with an AI assistant
You can use an AI assistant such as Claude or ChatGPT to find and fix the issue. Use one your company has approved for handling customer data. Attach your CSV and paste in this prompt:
I'm uploading this CSV to Vibe.co as a contacts list. The upload rejects the whole file if any single row is invalid. Please check every row and tell me the row numbers and values for any of these issues, then give me a corrected file:
The headers must be exactly: email, phone, firstName, lastName, postalAddress, city, zipCode, state, device_id. All 9 must be present, even if a column is empty.
Every row must have a valid email or a valid device_id (UUID format or a 64-character SHA-256 hash). Remove any completely blank rows, including at the end of the file. Flag any device_id value that isn't a valid UUID or 64-character SHA-256 hash.
Flag malformed emails: a dot right after the
@, consecutive dots, multiple@signs, a missing@, leading or trailing spaces, non-ASCII characters, more than one email in a cell, a domain starting or ending with a hyphen, and spreadsheet errors like#NAME?or#N/A.Hashed emails must be SHA-256: exactly 64 hex characters, with no prefix or salt.
Remove invisible characters anywhere in the file, including a BOM at the start, zero-width spaces, and carriage return (\r) characters at line endings.
Save the corrected file as a CSV with UTF-8 encoding, no BOM, and LF line endings.
Upload the corrected file directly, without opening it in Excel first.
Frequently Asked Questions
Q: What if I only have names and no email or phone?
A: Every row needs either a valid email address or a valid device ID. Names, phone numbers, and postal fields on their own aren't enough to make a row valid. If a contact has neither an email nor a device ID, that row can't be uploaded.
Q: Can I upload multiple CRM files at once?
A: No. You can only upload one file at a time per action. If you have multiple files, you'll need to upload and save them one by one
Q: Can I re-upload or replace a file after saving the audience?
A: Yes. You can remove a file and re-upload another one.
Q: Can I include both hashed and unhashed data in my file?
A: Yes. You can include plain-text emails, SHA-256 hashed emails, or both. If you upload plain text, we handle hashing and identity resolution for you. Other hash types (MD5, SHA-1, salted or prefixed hashes) aren’t supported, and a single row with one will cause the whole file to be rejected. If your data uses another hash type, upload plain-text emails instead.
Q: What if I only have partial postal address data?
A: That’s okay, as long as each row also has a valid email or device ID. Postal fields don’t make a row valid on their own, but they help us match more contacts. To use them for matching, include at least firstName, lastName and zipCode. Adding postalAddress, city and state improves match quality further.
Q: Why is my audience size showing as zero after upload?
A: If your data is still being processed, your audience status will show as Populating and may display 0 size temporarily. If processing finishes but no profiles could be matched, the status changes to No data. This usually means the contacts couldn’t be matched to households, which is common with work email addresses. Adding first name, last name and ZIP code can improve matching. If the status shows Error, the processing itself failed, so try uploading the file again.
Q: Can I track performance of CRM audiences in campaign reporting?
A: Yes. Once used in a campaign, your manual CRM audiences appear in the Custom Audiences reporting view. You'll see performance metrics like impressions, spend, conversions, etc.