Skip to end of metadata
Go to start of metadata

Last Updated: Friday, April 10, 2020



Overview

A Person entity is an identified entity that has interacted with or been loaded into the Mobile Database. It is identified by a person_key, which uniquely identifies the record, or an external_person_id, which is a unique identifier from the customer system for reference and cross-linking.

A Person can also be tracked/linked by a Mobile Directory Number (MDN). This alternate identifier is sufficient in the short-term, but it is not an ideal long-term identification method because mobile numbers can be changed, returned, ported, and recycled.

Topics in this Section




Note: If you are using Version 2 of the APIs, a mobile number must use the E.164 format. E.164 is the official format for all international phone numbers that includes a plus sign followed by the country code and phone number.

For example:

  • U.S.: +12135551234
  • U.K.: +442135551234

Associating Person Records

Because of the dynamic nature of mobile participation and campaigns, it is possible that Person records could exist in either the Mobile Database or the Customer system in any sequence/order. The following logic ensures that if the records exist in more than one place, the same Person entity gets tied together to avoid inadvertently linking two different people:

  1. 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/exist).
  2. 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.
Note: Since phone numbers often get ported and/or recycled, and to ensure Mobile Marketing Association (MMA) compliance, it is not a valid assumption that carrier changes are made to the same Person.

Person Entity

The following is the JSON representation of a Person entity within the APIs.

Note: The following example is of Version 2 of the APIs that uses the E.164 international MDN format. 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"
}

Elements

Data Element

Type

Description

person_idStringDEPRECATED This value is not used and will be removed in future API versions.

person_key

String

Vibes unique identifier for each Person record in the Mobile Database.

external_person_id

String

Customer unique identifier for a Person in the Mobile Database. This value is optional, but if specified, must be unique within the Mobile Database.  This value can only be up to 50 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 representation of 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, It must be in E.164 format, for example: +12195551234.

mobile_phone.carrier_code

String

The Cellular Carrier associated with this mobile number.

custom_fields

Object

Additional Field Types like String, Date, Single-Selection, and Multi-Selection.

Custom Field Types

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.

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 digit 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.
  • For multi selects, use a “|” pipe symbol to delineate multiple values in the same field.
  • Does not accept uppercase letters or spaces.

  • Cannot update an option_key after it's been created.

  • No labels

3 Comments

  1. Custom fields are marked as an Object because there is NO intent/use cases to where a caller needs to know dynamically the type of a field,and thus we will not be including it. In the case where a dynamic field parser is needed, that process can make a call to get custom fields which can contain all of that information. It will not be included within the Person object.

  2. Should we use machine friendly keys in the custom fields object? i.e. "first_name" instead of "First Name".

    1. Yes, we should. and yes we will.