Person Import
The person import allows you to use a file to batch upload person records into the Vibes Mobile Engagement Platform.
We recommend that you do a one-time load of initial data, then keep systems in sync with real-time API calls. However, if this is not possible, you can also provide a daily or weekly file to update the platform to changes in your system.
File Specifications
Encoding
UTF-8 or ASCII encoding for integration files is supported.
File Name
[filename].persons
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 Person Import. Using headers is optional.
| Header Name | Description |
|---|---|
| Fields | This 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. |
| Delimiter | The character used to delimit the columns. Defaults to a comma ",". |
| Multi-Select-Delimiter | The character used to delimit the multi-select values within a column. Defaults to a pipe "|". |
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, person_key, external_person_id, or mdn. If more than one value is specified, we will use the value with the highest precedence.
| 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 | If 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. |
mdn | String | The mobile phone number to include in the file body when updating the person record. Fourth in precedence. For non-US numbers, mdn must be in E.164 format. Example: mdn +12295551234. US numbers can use the 10-digit mdn format. |
| {custom} | String | Custom 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. Notes: - "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. - Custom field types include: date, number, single select, multi-select, string, and postal_code. |
Data
- Data in the file will override existing data in the Platform.
- The header row must match the name of the custom field EXACTLY.
Single and Multi-Select Fields
- For single and multi-select fields, the "option key" should be specified, not the value or ID. Note: The option key is case sensitive.
- For multi selects, use a "|" pipe symbol to delineate multiple values in the same field.
Clearing Out Custom Fields
On occasion, you may want to clear a custom field that was previously filled in a person record. To explicitly clear out a field using the person import, you can identify the record by the person_key and use a specific value to delete it from the person record. See the options below:
external_person_id- To clear from the person record, use the value [null]mdn– Unfortunately, an existing MDN cannot be modified using person import.- Single-Select Field - To clear from the person record, leave this field blank.
- Multi-Select Field - To clear from the person record, leave this field blank.
Errors
The following tables show error codes that can occur for person import files. Common errors can be found here.
Row-level errors
| Error Class | Error Message | Description |
|---|---|---|
| MobilePhoneErrors::InvalidMDNFormat | The MDN is incorrectly formatted. It should be an E.164 MDN. | |
| PersonErrors::CustomFieldNotFound | Custom field not found | There is a custom field column in the file that doesn't map to a valid custom field in the platform. |
| PersonErrors::InvalidSelectCustomFieldValue | Custom field value is incompatible with the field’s character set | The value for a string custom field contains characters outside the custom field's character set. |
| PersonErrors::InvalidSelectCustomFieldValue | Invalid custom field value | The value for a single-select or multi-select custom field in this row is not valid. |
| PersonErrors::PersonNotFound | Person not found | The given identifier doesn't point to a person record in the mobile database. |
| PersonErrors::MobilePhoneAlreadyAssigned | Mobile Phone Already Assigned | The MDN is already associated with an existing person. |
| PersonErrors::InvalidPersonID | Invalid person_id | The person_id is incorrectly formatted. |
| PersonErrors::MdnChangeNotAllowed | mdn change not allowed | The person in this row already has an MDN associated with their person record. |
| PersonErrors::PersonCreateRequiresDeviceOrExternalPersonId | Creating a person requires a device or an external person id | The row doesn't contain a value needed to create a person record. To create a person, you need one of the following: - MDN- vibes_device_id- external_person_id |
| PG::UniqueViolation | duplicate key value violates unique constraint | The external_person_id is already assigned to an existing person |
| CarrierLookupService::TransientLookupFailureError | A temporary issue with the carrier lookup service prevented the row from being processed. Please try again later. | |
| CarrierLookupService::PermanentLookupFailureError | The MDN supplied is not a valid mobile phone active on a valid carrier. |
File-Level Errors
| Error Class | Error Message | Description |
|---|---|---|
| PersonErrors::InvalidImportFileFormat | Couldn't find an external_person_id, mdn, or vibes_device_id field | The file is missing a column that identifies a person. At least one of following fields must be present: - external_person_id- mdn - vibes_device_id |
Example Files
file name: customer_test.persons
mdn,first_name,last_name,sport_interests
+12995550005,John,Doe,football|hockey
+12995550006,Mary,Sue,soccer
+12995550007,Dave,Doe,golf|basketball|hockey
+12995550008,John,Smith,soccer|football
See more examples by following 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 person import file in platform, the .csv extension should be deleted.
Updated about 2 months ago