Phone Number Representations

Apiture Open Banking APIs accept and manage the phone numbers of contacts, users, and organizations. The APIs accept phone numbers in many flexible formats, but always return phone numbers in a normalized E.164 format. This simplifies phone number processing for clients by providing a uniform format that is easily parsed, and clients can format phone numbers in the user’s preferred format.

Examples of valid input formats

In request bodies that include phone numbers, such as adding a phone number to a contact or organization, the input can match many common formats that people use.

  • Leading and trailing spaces are ignored.
  • The number may have a leading + and one- to three-digit country code prefix.
  • The number may use ( and ) around the area code.
  • The number may use - or . or spaces (ASCII 0x20) to separate the country code, area code, exchange, and number.
  • No other characters are allowed on input.
  • The default country code prefix is +1.

Examples:

(910) 555-0155
910 555-0155
910-555-0155
910.555.0155
9105550155
+1 (910)555-0155
+1  910  555 0155
+1 910.555.0155
+1 9105550155
+19105550155

The normalized E.164 format for all of the examples is

+19105550155

E.164 Phone Numbers in Responses

All operations which return phone numbers (GET operations, or response bodies from POST, PUT, or PATCH) represent them in this normalized E.164 format, such as

+19105550155

E.164 consists of the leading + character, a one- to three-digit country calling code (1 in this example), and up to 14 digits for the subscriber number (910-555-0155 in this example). After the +1 country code, U.S. numbers must contain exactly 10 digits.

We recommend using an open source library such as libphonenumber-js and others to parse and format E.164 phone numbers.