Subscriber Import

The Subscriber Import file is used to subscribe persons to an existing subscription list. You can use it to transfer existing subscription lists from another source into the Vibes platform.

In general, this bulk file import should only be used during the on-boarding process. If you have previously registered for subscription added callbacks, this import process will trigger a callback for each record included in the file.


Compliance note

This import should only be used to transfer a list of previously confirmed/opted-in subscribers from another source, as this import will not send a text to the consumer asking them to confirm their subscription. Adding subscribers who have not previously opted in violates federal compliance legislation.

File Specifications


UTF-8 or ASCII encoding for integration files is recommended.

File Name

[file name].subscriptions

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 subscriber import. Using headers is optional.

Header NameDescription
Content-TypeValue should always be TEXT.
Subscription-List-IDIf not specified here, it must be specified in every row. Any value specified in the row takes precedence over the header value.
FieldsThis is a comma-separated list of field names 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.
DelimiterThe character used to delimit the columns. If omitted, it defaults to a comma.


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.

If you are adding subscribers that do not already have a person record associated with them in your mobile database, new person records will be created using the MDN only. external_person_ids included for these person records will not be recorded.

For Subscription List imports, you will also need the include the subscription_list_id either in the header or in each row.

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

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_idStringThe external system's person ID to include in the subscription list. Third in precedence.

Note that external_person_id should only be used as an identifier if the external_person_id is already present in your mobile database. If the external_person_id does not already exist in your system, this column will be disregarded and the external_person_id will not be recorded.
mdnStringAn MDN is the mobile phone number to include in the subscription list.
- Non-US numbers must be in E.164 format. Example: mdn +12295551234
- US numbers can use the 10-digit MDN format
vibes_device_idStringThe Vibes-assigned identifier for a device that can receive push messages. The vibes_device_id must be lowercase.
subscription_list_idStringThe subscription list to which the person will be added. If not specified, the subscription-list-id from the header will be used.
opt_in_dateStringThe opt_in_date is optional but indicates the date/time that the subscriber had opted into the list. This can be backdated for historical purposes. Future values will generate an error. The value should be formatted in ISO 8601 format. ex: "2017-04-05T14:30Z" represents April 5th, 2017 at 2:30PM UTC.
carrier_codeStringThree-digit carrier code.
referring_applicationStringSource of subscription.
referring_application_ref_idStringSpecific ID of subscription source. This value, along with the above referring_application, can be used to assign and acquisition campaign to a given subscription.


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

Row-Level Errors

Error ClassError MessageDescription
PersonErrors::InvalidPersonKeyFormatThe person_key format is invalidThe person_key field is not formatted correctly.
MobilePhoneErrors::IllegalCarrierChangeThe carrier_code does not match the existincg carrier_codeThe carrier_code supplied with the MDN does not match the carrier_code associated with the MDN in the system.
SubscriptionErrors::SubscriptionAlreadyExistsThe mobile_phone is already subscribedThe mobile phone is already subscribed to the subscription list.
ListErrors::ListNotFoundThe subscription_list was not foundThe subscription_list_id didn't point to a valid subscription list.
MobilePhoneErrors::MobilePhoneNotFoundA mobile_phone was not foundA mobile phone could not be found with the given information in the record.
MobilePhoneErrors::InvalidMDNFormatThe mdn has an invalid formatThe mobile phone number is not a valid E.164 number.
SubscriptionErrors::OptInDateCannotBeInTheFutureThe opt_in_date cannot be in the futureThe opt-in date of the subscription cannot be in the future.
SubscriptionErrors::MdnChannelCountryCodeMismatchmdn country_code and short_code country_code do not matchThe country code of the MDN does not match the country code associated with the short code on the subscription list.
PersonErrors::InvalidPersonIDInvalid person_idThe person_id for this row is not formatted as a number.
MobilePhoneErrors::IncorrectCarrierIdProvidedCarrier ID validation failed for MDNThe carrier ID provided does not match the actual carrier ID of the MDN.
PushDeviceErrors::PushDeviceNotFoundA push_device was not foundNo push device was found.
SubscriptionErrors::AppIdMismatchDevice app_id does not match the list
CarrierLookupService::TransientLookupFailureErrorCarrier Lookup for failed with error General Processing ErrorA transient failure occurred when trying to verify the carrier of the MDN. Please try again.
CarrierLookupService::PermanentLookupFailureErrorCarrier Lookup for failed with error Looking up the carrier failed with an error that indicates it isn't likely to change.

File-Level Errors

Error ClassError MessageDescription
SubscriptionErrors::InvalidImportFileFormatCouldn't find a person_id, person_key, external_person_id, or mdn fieldThe file doesn't include one of the fields needed to identify the individual subscriber. One of the following is required:
- person_key
- person_id
- external_person_id
- mdn
SubscriptionErrors::InvalidImportFileFormatCouldn't find a subscription_list_idThe file doesn't indicate which list to subscribe the end users to.

Example Files

Download example files here.