You can use the Person API to update and retrieve person records. At Vibes, we identify each person with a person_key. However, if your system has its own way of identifying customers, you can use the external_person_id field to reference and cross-link.

Why use Person Records?

You may be wondering why Vibes uses person records, rather than just tracking end users by their MDN. While you can track and link your users with their unique MDN, it is not ideal for long-term identification. Since mobile numbers can be changed, returned, ported, and recycled, a person record is more accurate in the long term. This way, if a user changes their MDN, the rest of their information is not lost.

Person Record vs. Subscription Record – What’s the difference?

Though they might seem similar, it’s important to know the difference between person records and subscription records. A person record is unique for each end user and contains information that is unique to that person, such as their first name and zip code. A subscription record, however, is only unique to each time a person subscribes to a list. For example, one person record may have multiple subscription records if they are subscribed to multiple lists. Additionally, if one person unsubscribes and resubscribes to a list, there will be two subscription records created.

Available API Methods

Available Callbacks

Elements & Attributes

Data Element	Type	Description
`person_id`	Numeric	DEPRECATED A numeric identifier for a person record. Note that `person_id` is a deprecated field and may be removed in the future. We recommend using `person_key` whenever possible.
`person_key`	String	Vibes’ unique identifier for each person record in the mobile database.
`external_person_id`	String	A unique identifier for a person in the mobile database, as defined by you. This value is optional, but if specified, must be unique within the mobile database. This value can only be up to 128 characters long. Person identifiers that are canonical in external systems can be assigned to person resources in the `external_person_id` field. Any string value can be assigned as the external person id. If the `external_person_id` value contains non-URL-safe characters, they must be encoded if used in the URL.
`mobile_phone`	Object	Object representing a person's mobile phone. A person can have only one active mobile phone at a time.
`mobile_phone.mdn`	String	The Mobile Directory Number (a number that can be dialed). If you are using Version 1 of the APIs, do not use the E.164 MDN format. If you are using Version 2 of the APIs, use E.164 format. If you are including an MDN in a URL query string, be sure to encode the + as `%2B`.
`mobile_phone.carrier_code`	String	The cellular carrier code associated with this mobile number.
`custom_fields`	Object	An object containing any additional custom fields.

Custom fields

In addition to the above fields, you can also customize your person records with custom fields that store data relevant to your campaigns. Below is a list of the types of fields you can use to make custom fields.

Field Type	Value Representation
String	Value: String To clear a string custom field of its value, send null.
Timestamp	Value: Date. It should be in the ISO 8601 format - for example: 2017-01-05T14:30Z. To clear a date custom field of its value, send null.
Single-Selection	Object with :id and :name.
Multi-Selection	An array of objects, with each object having the content of a single select. The example below shows an array for the custom field `favorite_stores`. Note that with each update of a person record, all selected options must be present in the array; any that are missing will be removed from the person record. Example of array*: `"custom_fields":{` `"favorite_stores":[` `{` `“id”:“4”,` `“name”:“My Hardware Store”,` `“option_key”:“my_hardware_store”` `},` `{` `“id”:“12”,` `“name”:“Local Grocery”,` `“option_key”:“local_grocery”` `}` `],` `}`
Numeric	Type: number. “values” is ignored if provided. Limitations: Only charset allowed is ASCII Only accepts JSON numbers (Strings are not allowed) Length in total must be less than 10 (decimal and negative sign each count as 1 so -1.2 is a total of 4) Number of digits after a decimal can be at most 3

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.
Does not accept uppercase letters or spaces.
Cannot update an option_key after it's been created.

Example Entity

The following is the JSON representation of a person entity within the APIs. Note that the example is of Version 2 of the APIs that uses the E.164. If you are using Version 1 of the API, you cannot use the E.164 format.

{
   "person_id":"123455",
   "person_key":"c5235a1-e243-42z7-979c-7f6234kl21b60",
   "external_person_id":"542342",
   "mobile_phone":{
      "mdn":"+12995551234",
      "carrier_code":"104"
   },
   "custom_fields":{
      "first_name":"Steve",
      "birthdate":"1950-12-01T00:00:00Z",
      "rewards_id":"543557654",
      "favorite_stores":[
         {
            "id":"4",
            "name":"My Hardware Store"
         },
         {
            "id":"12",
            "name":"Local Grocery"
         }
      ]
   },
   "created_at":"2017-01-05T14:30Z",
   "updated_at":"2017-02-08T19:30Z",
   "url":"/companies/:company_key/mobiledb/persons/:person_id"
}

Associating Person Records

Because of the dynamic nature of mobile participation and campaigns, it is possible that person records could exist in both our mobile database and an external system. To ensure that records for the same person are tied together correctly, Vibes uses the following logic:

The person_key and external_person_id columns are always treated as the same person record and must be unique (the external_person_id can be omitted if it is not used).
If the MDN and carrier_code match an existing person record, they will be considered the same person entity. If the carrier_code does not match, then they will be assumed to be different people.