Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Last Updated:


placeholderSearch the Vibes Developer Wiki

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.

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

File Name 


File Format

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.

Note: Using headers is entirely optional.

Header Name



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 "|".

File Body

The file body can contain the following fields as data, separated by the delimiter.

Note: The field names must be lowercase.

Field Name

Data Type




The Mobile Database Person ID to include in the file body when updating the Person record.

person_keyStringThe Person Key is a UUID to include in the Person Import. The person_key must be lowercase.



The external system's Person ID to include in the file body when updating the Person record.



A Mobile Directory Number (mdn) is the mobile_phone number to include in the file body when updating the Person record.

  • For non-US numbers, the Mobile Directory Number (mdn) must be in E.164 format.




  • US numbers can use the 10-digit mdn format.



A Person custom field.

Note: "Custom" is not a specific string. It means that any custom field name may be used in the data file.

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.

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.

Error Messages

The following tables show the error codes that can occur when importing a file.

Row Level Errors

Error Class

Error Message


The mdn is incorrectly formatted. It should be an E.164 mdn.
PersonErrors::CustomFieldNotFoundCustom field not foundThere is a custom field column in the file that doesn't map to a valid custom field.
PersonErrors::InvalidSelectCustomFieldValueCustom field value is incompatible with the field’s character setThe value for a string custom field contains characters outside the custom field's character set.
PersonErrors::InvalidSelectCustomFieldValueInvalid custom field valueThe value for a single-select or multi-select custom field in this row is not valid.
PersonErrors::PersonNotFoundPerson not foundThe given person_id or person_key doesn't point to an actual Person.
PersonErrors::MobilePhoneAlreadyAssignedMobile Phone Already AssignedThe mdn is already associated with an existing person.
PersonErrors::InvalidPersonIDInvalid person_idThe person_id is incorrectly formatted.
PersonErrors::MdnChangeNotAllowedmdn change not allowedThe Person in this row already has an mdn.
PersonErrors::PersonCreateRequiresDeviceOrExternalPersonIdCreating a Person requires a device or an external person idThe 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::UniqueViolationduplicate key value violates unique constraintThe external_person_id is already assigned to an existing person
A temporary issue with the carrier lookup service prevented the row from being processed. Please try again later.
The mdn supplied is not a valid mobile phone active on a valid carrier.

File Level Errors

Error Class

Error Message


PersonErrors::InvalidImportFileFormatCouldn't find a person_id, external_person_id, mdn, or vibes_device_id fieldThere is not a column in the file that identifies a Person.

Common Errors

The following errors can occur in imports of all file types.

File Level Errors

Error Class

Error Message



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.

Example File

Code Block
titlefile name: customer_test.persons

See the attached files for additional examples of Person Import files.