CSV Field Definitions

Detailed formatting rules for every column in the Reach bulk upload CSV template, with common mistakes and how to avoid them.

Overview

Every column in the Reach bulk upload CSV has specific formatting rules. Get one wrong and that row fails. This article covers every field in detail: what it does, whether it is required, exactly what format it expects, and common mistakes to avoid.

Field-by-Field Reference

Subscriber_Id

Required? No. Leave blank to create a new subscriber. Enter an existing Subscriber ID to update that record. The ID is alphanumeric and case-sensitive. You can find a subscriber's ID by searching for them in the Subscribers tab.

first_name

Required? Yes. The subscriber's first name. Alphanumeric characters only. No special characters, apostrophes, hyphens, or accents. Maximum length follows standard text field constraints.

last_name

Required? Yes. The subscriber's last name. Same rules as first_name: alphanumeric only.

city

Required? No. Full city name as plain text. Used in Analytics subscriber filters for geographic segmentation.

state

Required? No. Must be exactly two characters: the standard US state abbreviation. MN for Minnesota, NY for New York, FL for Florida, and so on. Entering a full state name will cause validation to fail for that row.

zipcode

Required? No. Numeric zip code only. No formatting or dashes (e.g., enter 10103 not 10103-4567).

email_address1

Required? Required if you are assigning the Email channel. Must be a valid email address format: name@domain.com. No leading or trailing spaces. This is the address Reach will send all email notifications to for this subscriber.

mobile_number1

Required? Required if you are assigning the SMS channel. Digits only. No dashes, spaces, parentheses, or plus signs. US numbers: 10 digits (e.g., 6125550199). International numbers: up to 16 digits. Reach routes international numbers automatically.

voice_number1

Required? Required if you are assigning the Voice channel. Same format rules as mobile_number1. This can be the same number as mobile_number1 or a different one.

Quick Reference Table

Field	Required?	Format	Common mistake
Subscriber_Id	No	Alphanumeric, case-sensitive	Including an ID that does not exist in Reach
first_name	Yes	Alphanumeric only	Using apostrophes or accented characters
last_name	Yes	Alphanumeric only	Using hyphens in hyphenated last names
city	No	Plain text	No issues common
state	No	Exactly 2 letters	Writing 'Minnesota' instead of 'MN'
zipcode	No	Digits only	Including a dash (10103-4567)
email_address1	For email channel	name@domain.com	Extra spaces before or after the address
mobile_number1	For SMS channel	Digits only, 10-16 digits	Including dashes or parentheses
voice_number1	For voice channel	Digits only, 10-16 digits	Same as mobile_number1

Having Trouble?

What you're seeing	Why it happens	How to resolve it
Rows fail with a 'state' error	The state value is more than 2 characters or contains a full state name.	Replace all state values with the correct 2-letter abbreviation.
Rows fail with a phone number error	The phone number contains formatting characters or is the wrong length.	Remove all dashes, spaces, and parentheses. US numbers should be 10 digits.
Rows fail with a 'missing required field' error	first_name, last_name, or a required channel field is blank.	Fill in the missing values and re-upload only the failed rows.
Rows fail with a 'Subscriber ID not found' error	A Subscriber_Id was provided but does not match any record in the selected department.	Verify the ID in the Subscribers tab. If adding new, leave the Subscriber_Id column blank.
Upload processes but email notifications are not sent	email_address1 was blank or the Email channel was not selected in Assign Criteria.	Check both the CSV data and the channel assignment in the upload wizard.

Frequently Asked Questions

Q: Can I have more than one phone number per subscriber?

A: The standard template has one mobile number and one voice number. For additional contact numbers, contact Convey support about your configuration options.

Q: What happens if I provide an email address but did not select the Email channel in the upload?

A: The address is stored on the subscriber record, but no email notifications will be sent unless the Email channel is assigned. You can re-upload or edit the subscriber to correct this.

Q: Is there a maximum length for name fields?

A: The fields accept standard text lengths. Very long names (over 100 characters) may cause unexpected behavior. Keep names to realistic lengths.

Q: Can I use a P.O. Box in the city or address field?

A: The CSV template does not have a dedicated street address field. City, state, and zip are the available location fields in the bulk upload template.

Need More Help?

If you have followed the steps above and still require assistance, please refer to the relevant articles listed below for additional guidance.

Download CSV Template Get the official template with correct headers.
How to Fix Upload Errors How to find and fix failed rows after an upload.

Related to