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


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

File Name


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 Person Import. Using headers is optional.

Header NameDescription
FieldsThis 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.
DelimiterThe character used to delimit the columns. Defaults to a comma ",".
Multi-Select-DelimiterThe 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. 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 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_idStringIf 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.
mdnStringThe 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:

US numbers can use the 10-digit mdn format.
{custom}StringCustom 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.

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


The following tables show error codes that can occur for person import files. Common errors can be found here.

Row-level errors

Error ClassError MessageDescription
MobilePhoneErrors::InvalidMDNFormatThe 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 in the platform.
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 identifier doesn't point to a person record in the mobile database.
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 associated with their person record.
PersonErrors::PersonCreateRequiresDeviceOrExternalPersonIdCreating a person requires a device or an external person idThe row doesn't contain a value needed to create a person record. To create a person, you need one of the following:
- vibes_device_id
- external_person_id
PG::UniqueViolationduplicate key value violates unique constraintThe external_person_id is already assigned to an existing person
CarrierLookupService::TransientLookupFailureErrorA temporary issue with the carrier lookup service prevented the row from being processed. Please try again later.
CarrierLookupService::PermanentLookupFailureErrorThe MDN supplied is not a valid mobile phone active on a valid carrier.

File-Level Errors

Error ClassError MessageDescription
PersonErrors::InvalidImportFileFormatCouldn't find an external_person_id, mdn, or vibes_device_id fieldThe 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


Download more examples here.