# FORMAT\_PHONE

**The FORMAT\_PHONE function outputs a phone number with desired formatting.**

The FORMAT\_PHONE function takes a phone number and returns a [string](../../variable-data-types/the-text-variable-data-type) containing the same phone number formatted in either an **international**, **national**, or **RFC3966 tel: URI** format.

#### Declaration

```javascript
FORMAT_PHONE(phone_number_string, format_string, region) -> formatted_phone_number
```

#### Parameters

**phone\_number\_string** (required, type: _string_) A string containing a phone number.

**format\_string** (required, type: _string_) The format to return the phone number in (any of "[E164](https://en.wikipedia.org/wiki/E.164)", "INTERNATIONAL", "NATIONAL", "RFC3966").

**region** (optional, type: _string_, default: the 2-digit country code indicated by **phone\_number\_string**) String representing the 2-digit country code. If **phone\_number\_string** is not in proper E.164 format and doesn't contain a country code, the region indicated by **region** will be used to determine the country code. (Note that an E.164 country code and a 2-digit country code will _not_ be represented by the same string.)

#### Return Values

**formatted\_phone\_number** (type: _string_) String containing the formatted phone number.

#### Examples

When displaying a phone number to a user, it is common to group the digits of the phone number so that it can more easily be read. The format strings **"NATIONAL"** will omit the country code of the phone number and group the digits in the phone number according to the conventions for the country. Compare how a U.S. phone number is presented compared to an Australian phone number.

```javascript
FORMAT_PHONE("+17167762323", "NATIONAL") -> "(716) 776-2323"
```

```javascript
FORMAT_PHONE("+610255501234", "NATIONAL") -> "(02) 5550 1234"
```

The **"NATIONAL"** format string should only be used it will be obvious to a user which country the phone number belongs to. For example, when displaying a user's own phone number, using national formatting is fine as the user will recognize their own number. However, when displaying an unknown phone number, or when displaying multiple phone numbers from different countries, using the format string **"INTERNATIONAL"**, will be more clear.

```javascript
FORMAT_PHONE("+17167762323", "INTERNATIONAL") -> "+1 716-776-2323"
```

```javascript
FORMAT_PHONE("+610255501234", "INTERNATIONAL") -> "+61 2 5550 1234"
```

The format string **"RFC3966"** is needed when communicating with external systems that require the format.

```javascript
FORMAT_PHONE("+17167762323", "RFC3966") -> "tel:+1-716-776-2323"
```

```javascript
FORMAT_PHONE("+610255501234", "RFC3966") -> "tel:+61-2-5550-1234"
```

If a phone number has been collected from a user, it may not be in proper E.164 format. The string **"7167762323"** is ambiguous without a country code. However, information on the country can be provided separately via the variable **region**. Note that if a value is given for **region**, a value must be given for **format\_string**:

```javascript
FORMAT_PHONE("7167762323", "E164", "US") -> "+17167762323"
```

Providing a value for **region** will not overrun information given by a country code in a given phone number. The following example takes an Australian phone number in E.164 format and outputs the same Australian phone number in E.164 format, even though the given value for **region** indicates that the phone number is from the US region:

```javascript
FORMAT_PHONE("+610255501234", "E164", "US") -> "+610255501234"
```
