E.164 Support for Platform APIs

E.164 Phone Number Support

E.164 is the official format for all international phone numbers that includes a plus sign (+) followed by a country code and phone number.

For example:

• U.S.: +12025550132
• U.K.: +441632960964
• Brazil: +5511991234567

Version 2 of the following Platform APIs now accept and return phone numbers in the standard E.164 format.:

• Acquisition API
• Person API
• Subscription List API
• Event API

The following is a partial API example showing how the E.164 format is displayed.

{
   "person_id":"c5235a1-e243-42z7-979c-7f6234kl21b60",
   "external_person_id":"542342",
   "mobile_phone":{
      "mdn":"+12025550132",
      "carrier_code":"104"
   },

Platform APIs Accept MDNs in E.164 Format

Version 2 of the APIs only accepts MDNs in E.164 format if they include a country code.

MDNs without a country code are considered invalid.

Subscription Entity Example

{
...
"id": 25,  
"mobile_phone": {
    "mdn": "+441632960964",
    "carrier_id": "105",
    "device_uid":  "1237533a-12ff-1235-9b8f-b139fbbf7123"
}
...

Platform APIs Return MDNs in E.164 Format

MDNs are returned in E.164 format. Phone numbers that were stored using Version 1 of the APIs are assumed to be US/Canada (+1) phone numbers. 

Person Entity Example

{
...
 "id": 4,
 "mobile_phone": { "mdn": "+12025550132",
                    "carrier_id": "104",
                    "device_uid":  "1237533a-12ff-1235-9b8f-b139fbbf7123",
...
}

Persons with International MDNs not Returned in Version 1

If you use Version 1 of the Platform APIs, a CountryNotSupported error will be returned if you query for a Person with an MDN that does not follow the E.164 format, for example, if it is a U.S. number and you use 2135551234 instead of +12135551234.