This page documents the file format the platform expects when you upload contacts for a first-party data respondent source, an interactive Twilio text respondent source, or a Twilio voice respondent source. The same parsing rules apply to all three.
Accepted file types
.xlsx— Excel workbook..csv— plain comma-separated values, UTF-8..csv.gz— gzipped CSV.
Identity column
Every upload must contain the configured identity column. By default this is named Identifier, but the column name is configurable on the respondent source. The values in this column must be unique within the file — if any value appears more than once, the upload is rejected. De-duplicate before uploading.
What the identity column holds depends on the respondent source:
- First-party data: a customer ID, hashed email, or any value that is unique per respondent. Avoid PII where possible — the platform scrubs this field, but defence in depth is sensible.
- Interactive text and voice: phone numbers in E.164 format. Numbers not in E.164 are rejected.
Excel parsing rules
You do not need to format the data as an Excel table (Insert → Table). A plain worksheet works. The platform reads the workbook as follows:
- Active sheet only. The workbook's active sheet (the one open when the file was last saved) is the sheet that's read. Other sheets in the workbook are ignored.
- First non-empty row is the header. Scanning down the active sheet, the first row that contains any data is treated as the header row. Blank rows before that row are tolerated.
- Headers must be non-blank and unique. Every column in the header row must have a value, and no two columns can share the same header.
- Data rows are read directly from the sheet. There's no bounded table range — every row after the header is considered a candidate data row.
- Empty rows after the header are skipped. Blank rows interspersed with data are tolerated and dropped by the contact builder. A trailing run of blank rows does not cause an error.
Errors
If the platform cannot read the workbook — corrupted file, unsupported format inside the workbook, or any other parsing failure — the upload returns a generic import error. Re-export the data and try again; if the error persists, get in touch.
CSV parsing
CSV uploads (.csv, .csv.gz) are read straight through: the first row is the header, every subsequent row is a candidate data row. The same identity-column, uniqueness, and header rules apply.