Last Updated: Wednesday, June 24, 2020
You can upload custom field data about any Persons in your Mobile Database, or Persons who may join your Mobile Database at some point in the future. This allows you to keep Vibes Mobile Engagement Platform in sync with updates that happen to your Customer Relationship Management (CRM) system. We recommend that you do a one-time load of initial data, then keep systems in sync with real-time Application Program Interface (API) calls. Alternatively, you can also provide a daily or weekly file to update the Platform to changes in your system.
The file format is a Comma-Separated Values (CSV) file. This stores tabular data (numbers and text) in plain text, where the line of the file is a data record. Each record consists of one or more fields, separated by commas.
When specifying data for a Date field, the format is "YYYY-MM-DDTHH:MM:SSZ" for UTC time, or "YYYY-MM-DDTHH:MM:SS-TTTT" where TTTT is the time offset.
You can include the following headers in your Person Import.
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.
The character used to delimit the columns. Defaults to a comma ",".
The character used to delimit the multi-select values within a column. Defaults to a pipe "|".
The file body can contain the following fields as data, separated by the delimiter.
The Mobile Database Person ID to include in the file body when updating the Person record. First in precedence.
|person_key||String||The Person Key is a UUID to include in the Person Import. The person_key must be lowercase. Second in precedence.|
The external system's Person ID to include in the file body when updating the Person record. Third in precedence.
A Mobile Directory Number (mdn) is the mobile_phone number to include in the file body when updating the Person record. Fourth in precedence.
A Person custom field.
For a particular row, only one of person_id, external_person_id, person_key, or mdn need to be specified, as these are alternate means of referencing a Person. If more than one value is specified, we will use the value with the highest precedence. The precedence order is shown in the table above.
- 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 the external_person_id field
To explicitly clear out an external person, you can identify the record by the person_key or person_id, and use the value [null] (including the 's) as the external_person_id value to delete it from the person record.
The following tables show the error codes that can occur when importing a file.
|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.|
|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 person_id or person_key doesn't point to an actual Person.|
|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.|
|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. It is missing either a mdn, vibes_device_id, or 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.|
|PersonErrors::InvalidImportFileFormat||Couldn't find a person_id, external_person_id, mdn, or vibes_device_id field||There is not a column in the file that identifies a Person. None of following fields are present: person_id, external_person_id, mdn, or vibes_device_id field|
The following errors can occur in imports of all file types.
|Schema name for company <company_id> (is nil|was not found)||The company that the file is target for is not set up in MobileDB, or there was some other system level error.|
See the attached files for additional examples of Person Import files.