Recipient List Import

Much like the person import, a recipient list is also a collection of persons. However, a recipient list is a collection of persons to target in a broadcast or file-triggered broadcast. The most common use case is when your CRM has created a list of contacts to target. The list can then be loaded into the Vibes platform and used for a broadcast.

Recipient lists can also include additional columns of data that can be used as message variables or the entire message itself. For example, if you had a column titled “first_name”, you could pull that personalization value into a broadcast or file-triggered message.

Which identifier should I use?

Recipient lists may be channel-specific depending on the fields you use to identify each person.

  • If the file identifies person records by person_id, person_key, or external_person_id, you can send SMS, MMS, or push messages
  • If the file identifies person records by mdn only, you can only send SMS or MMS messages
  • If the file identifies person record by vibes_device_id only, you can only send push messages


Using custom data

Using a recipient list will not update person records. If you include custom data for personalization in your recipient list, it will not be stored in your mobile database.

File Specifications


UTF-8 or ASCII encoding for integration files is recommended. UTF-16LE encoding is not supported.

File Name

[file name].recipient_list

File Format

The contents of the file should be plain text separated by commas or another delimiter.

File Size

If you are uploading via the platform, we recommend files are less than 5MB, which is usually about 100,000 rows of data.

If you are uploading files via SFTP, there is no limit; however, larger files may take more time to upload.


You can include the following headers in your Recipient List Import. Using headers is optional.

Header NameDescription
Content-TypeValue should always be TEXT.
List-NameThis is the list name that will be displayed in the User Interface. If omitted, a default value based on the filename will be used.
FieldsThis is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names, with the same delimiter as the body.


The file body can contain the following fields as data. All field names must be lowercase.

In each row, at least one identifier needs to be specified. Available identifiers are person_id, external_person_id, person_key, vibes_device_id, or mdn. If more than one value is specified, we will use the value with the highest precedence.

Field NameData TypeDescription
person_idIntegerA Vibes-assigned number identifier, used to identify a person record that already exists in the Vibes system. First in precedence.
person_keyStringThe Vibes-assigned string identifying a person record that already exists in the Vibes system. The person_key must be lowercase. Second in precedence.
external_person_idStringIf your external system uses its own system of id, use the external_person_id field to upload this data into the Vibes system. Third in precedence.
vibes_device_idStringA unique identifier for a device that can receive push notifications. The vibes_device_id must be lowercase. Fourth in precedence.
mdnStringAn mdn is the mobile phone number to send the message to.

- For non-US numbers, the mdn must be in E.164 format. Example: mdn +12295551234
- US numbers can use the 10-digit mdn format.
{custom}StringCustom fields are fields that are specified by you. Any custom fields you’d like to use must be created in the platform before they are used in a person import.

- "Custom" is not a specific string. It means that any custom field name may be used in the data file.
- The header row must match the name of the custom field EXACTLY.
segment_codeStringA custom string that can be used for targeting.

Note: You can only use the segment_code option in broadcasts − it is not supported in file-triggered messages.
client_message_idStringA custom string that can be later tracked through exports from our data warehouse.


The following tables show error codes that can occur for recipient list import files. Common errors for all file types can be found here.

Row-Level Errors

Error ClassError MessageDescription
RecipientListEntryErrors::DuplicatePersonIdduplicate person_idThe recipient list already has a row with this person_id.
RecipientListEntryErrors::DuplicatePersonKeyduplicate person_keyThe recipient list already has a row with this person_key.
RecipientListEntryErrors::DuplicateExternalPersonIdduplicate external_person_idThe recipient list already has a row with this external_person_id.
RecipientListEntryErrors::DuplicateMDNduplicate mdnThe recipient list already has a row with this MDN.
RecipientListEntryErrors::DuplicateVibesDeviceIdduplicate vibes_device_idThe recipient list already has a row with this vibes_device_id.
RecipientListEntryErrors::InvalidPersonIdinvalid person_idThe person_id or person_key in this record doesn't point to a valid person record in our mobile database, or the person_id is formatted incorrectly.
RecipientListEntryErrors::InvalidMDNinvalid mdnThe MDN isn't a valid E.164 phone number.
PG::NumericValueOutOfRangeinteger out of rangeThe error message means the import has a number that’s too big for our database to handle.

File-Level Errors

Error ClassError MessageDescription
RecipientListErrors::RecipientListAlreadyExistsA recipient list with that name already exists.
RecipientListErrors::InvalidImportFileFormatCouldn't find a person_id, external_person_id, mdn, or vibes_device_id fieldThe file does not include a field that can be used to identify the person or device you are sending to. One of the following fields must be present:
- person_id
- person_key
- external_person_id
- mdn
- vibes_device_id
RecipientListErrors::InvalidImportFileFormatspecify an mdn, or a vibes_device_id, or neitherThe file attempts to identify persons by both an MDN and vibes_device_id. Choose only one identifier, or remove both and add another identifier.
RecipientListErrors::InvalidImportNoValidEntriesThere are no valid entries in the file, so the recipient list was not created.
RecipientListErrors::SegmentCodeLimitExceededYou have too many unique values for the segment code. (max 100)

Example Files

Download example files here.