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
Encoding
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.
Headers
You can include the following headers in your subscriber import. Using headers is optional.
| Header Name | Description |
|---|---|
| Content-Type | Value should always be TEXT. |
| Subscription-List-ID | The numeric ID for the subscription list the subscribers should be added to. You can find this numeric ID in the URL when you navigate to the list the Vibes platform. If not specified here, it must be specified in every row. Any value specified in the row takes precedence over the header value. |
| Fields | This 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. |
| Delimiter | The character used to delimit the columns. If omitted, it defaults to a comma. |
Body
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. All other fields are not required and can be left blank if needed, but at least one identifier is required.
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 Name | Data Type | Description |
|---|---|---|
person_id | Integer | A Vibes-assigned number identifier, used to identify a person record that already exists in the Vibes system. First in precedence. |
person_key | String | The 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_id | String | The 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. |
mdn | String | An 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_id | String | The Vibes-assigned identifier for a device that can receive push messages. The vibes_device_id must be lowercase. |
subscription_list_id | String | The subscription list to which the person will be added. You can find the numeric ID of a subscription list in the URL when you navigate to the list in the platform. If not specified, the subscription-list-id from the header will be used. |
opt_in_date | String | The 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_code | String | Three-digit carrier code. |
referring_application | String | Source of subscription. For migration purposes, we recommend setting up an acquisition campaign in the platform to correspond with the original opt-in source. The value in this column should be splat, which refers to the Vibes platform. |
referring_application_ref_id | String | Campaign ID of subscription source. For a subscriber import, this is the numeric id of an acquisition campaign. In order to properly map subscriptions to an acquisition campaign, the referring_application should be splat. This can be used later to segment your campaigns by subscription source. |
Errors
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 Class | Error Message | Description |
|---|---|---|
| PersonErrors::InvalidPersonKeyFormat | The person_key format is invalid | The person_key field is not formatted correctly. |
| MobilePhoneErrors::IllegalCarrierChange | The carrier_code does not match the existincg carrier_code | The carrier_code supplied with the MDN does not match the carrier_code associated with the MDN in the system. |
| SubscriptionErrors::SubscriptionAlreadyExists | The mobile_phone is already subscribed | The mobile phone is already subscribed to the subscription list. |
| ListErrors::ListNotFound | The subscription_list was not found | The subscription_list_id didn't point to a valid subscription list. |
| MobilePhoneErrors::MobilePhoneNotFound | A mobile_phone was not found | A mobile phone could not be found with the given information in the record. |
| MobilePhoneErrors::InvalidMDNFormat | The mdn has an invalid format | The mobile phone number is not a valid E.164 number. |
| SubscriptionErrors::OptInDateCannotBeInTheFuture | The opt_in_date cannot be in the future | The opt-in date of the subscription cannot be in the future. |
| SubscriptionErrors::MdnChannelCountryCodeMismatch | mdn country_code and short_code country_code do not match | The country code of the MDN does not match the country code associated with the short code on the subscription list. |
| PersonErrors::InvalidPersonID | Invalid person_id | The person_id for this row is not formatted as a number. |
| MobilePhoneErrors::IncorrectCarrierIdProvided | Carrier ID validation failed for MDN | The carrier ID provided does not match the actual carrier ID of the MDN. |
| PushDeviceErrors::PushDeviceNotFound | A push_device was not found | No push device was found. |
| SubscriptionErrors::AppIdMismatch | Device app_id does not match the list | |
| CarrierLookupService::TransientLookupFailureError | Carrier Lookup for failed with error General Processing Error | A transient failure occurred when trying to verify the carrier of the MDN. Please try again. |
| CarrierLookupService::PermanentLookupFailureError | Carrier 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 Class | Error Message | Description |
|---|---|---|
| SubscriptionErrors::InvalidImportFileFormat | Couldn't find a person_id, person_key, external_person_id, or mdn field | The 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::InvalidImportFileFormat | Couldn't find a subscription_list_id | The file doesn't indicate which list to subscribe the end users to. |
Example Files
Below, you can download a .zip of example files of a subscriber import. To view these files, follow the following steps.
- Download example files here.
- View the file in your downloads folder. Click to unzip.
- Rename each unzipped file by adding .csv to the end. This will change the file's extension, therefore making it viewable in Microsoft Excel.
- Open the file in Microsoft Excel or another spreadsheet app to view.
Note that when you upload a subscriber file in platform, the .csv extension should be deleted.
Updated about 1 month ago