User import CSV

The user import lets you create and update users in bulk. Users are matched by phone number: an existing user is updated, and a new user is created if no match is found.

Delivery: place the file in the SFTP inbound directory provisioned for your account. Sotto picks up new files automatically and routes them by their filename prefix — a file must start with user to be processed as a user import. Files whose name doesn’t match a known type are not processed.

File requirements

Property	Value
Format	CSV (comma-separated values)
Encoding	UTF-8
Filename	Prefixed with `user_`
Delimiter	Comma (`,`)
Text qualifier	Optional; required only for values containing commas
Header row	Required. Optional columns may be omitted entirely.
Date format	`MM/DD/YYYY`
Phone format	E.164 (e.g. `+15551234567`)

Standard columns

Column	Required	Format	Description
`phone_number`	Yes	E.164	Unique identifier for the user. Must include the country code and leading `+`.
`messaging_consent`	No	`opted_in`, `opted_out`, or `initial`	SMS marketing consent. Defaults to `initial` for new users.
`first_name`	No	Text	The user’s first name.
`last_name`	No	Text	The user’s last name.
`email_address`	No	Email	The user’s email address.
`date_of_birth`	No	`MM/DD/YYYY`	Invalid formats are skipped with a warning.
`postal_code`	No	5-digit US ZIP	The user’s postal code. US only.
`third_party_id`	No	Text	Your own unique identifier for the user.

Custom data columns

Import business-specific attributes by prefixing the column name with custom_, followed by the configured field name: custom_{field_name}. For example, a field named “Loyalty Tier” maps to the column custom_loyalty_tier.

Only custom fields already configured for your brand are processed. Unrecognized custom columns are skipped with a warning. You can list your configured fields with the Custom Data endpoint.

Data type	Format	Example
Integer	Whole number	`42`
Float	Decimal number	`19.99`
String	Text	`gold`
Boolean	`true` / `false` (case-insensitive)	`TRUE`
List	Pipe-delimited values	`electronics\|gaming\|tech`

Example

phone_number,first_name,last_name,email_address,messaging_consent,date_of_birth,third_party_id,custom_loyalty_tier,custom_interests,custom_vip_status
+12025551234,John,Doe,john@example.com,opted_in,03/15/1990,CUST-001,gold,electronics|gaming|tech,true
+12025551235,Jane,Smith,jane@example.com,initial,07/22/1985,CUST-002,silver,fashion|beauty,false
+12025551236,Bob,Johnson,bob@example.com,,12/01/1992,CUST-003,bronze,,false

Behavior

New users
Existing users

Rows with a valid phone number that doesn’t match an existing user create a new record.
Missing optional fields are left blank.
Custom data is set from the provided values.

Error handling

Condition	Behavior	Impact
Invalid phone number	Row skipped, error logged	User not created/updated
Invalid `messaging_consent` value	Row skipped, error logged	User not created/updated
Invalid date format	Date field skipped, warning logged	Rest of row processed
Custom data type conversion error	Field skipped, warning logged	Rest of row processed
Unrecognized custom field	Field skipped, warning logged	Rest of row processed
Missing `phone_number` column	Import aborted	No users processed

Before you import

Confirm the phone_number column exists

It is the only required column, and every value must be valid E.164.

Validate consent values

messaging_consent, if present, must be opted_in, opted_out, or initial.

Check dates and custom columns

Dates use MM/DD/YYYY; custom columns use the custom_ prefix and pipe-delimited lists.

Get started

Webhooks

Bulk data

Reference

User import CSV

File requirements

Standard columns

Custom data columns

Example

Behavior

Error handling

Before you import

​File requirements

​Standard columns

​Custom data columns

​Example

​Behavior

​Error handling

​Before you import

File requirements

Standard columns

Custom data columns

Example

Behavior

Error handling

Before you import