PhoneNumber

  • This document outlines a standard JSON structure for representing phone numbers, including the main number, extension, and preferred domestic carrier code.

  • Phone numbers are stored in E.164 format, an international standard defined by the International Telecommunication Union.

  • Extensions, while not standardized, are included to accommodate diverse organizational practices and can hold digits or other dialing characters.

  • The preferredDomesticCarrierCode field stores carrier selection codes that might be required for domestic calls in specific scenarios, such as landline to mobile calls.

Standard phone number representation.

JSON representation 
{
  "e164PhoneNumber": string,
  "extension": string,
  "preferredDomesticCarrierCode": string
}
Fields
e164PhoneNumber

string

Phone number in E.164 format, as defined in International Telecommunication Union (ITU) Recommendation E.164. wiki link: https://en.wikipedia.org/wiki/E.164
extension

string

Extension is not standardized in ITU recommendations, except for being defined as a series of numbers with a maximum length of 40 digits. It is defined as a string here to accommodate for the possible use of a leading zero in the extension (organizations have complete freedom to do so, as there is no standard defined). Other than digits, some other dialling characters such as "," (indicating a wait) may be stored here. For example, in xxx-xxx-xxxx ext. 123, "123" is the extension.
preferredDomesticCarrierCode

string

The carrier selection code that is preferred when calling this phone number domestically. This also includes codes that need to be dialed in some countries when calling from landlines to mobiles or vice versa. For example, in Columbia, a "3" needs to be dialed before the phone number itself when calling from a mobile phone to a domestic landline phone and vice versa. https://en.wikipedia.org/wiki/Telephone_numbers_in_Colombia https://en.wikipedia.org/wiki/Brazilian_Carrier_Selection_Code

Note this is the "preferred" code, which means other codes may work as well.