# Manage Phone Numbers

Phone numbers are a central part of the **Telephony SDK**. Phone numbers from different countries around the world can be provisioned and used to to communicate with other phone numbers.

Provisioning a phone number is a two-step process. First, a search must be performed for an available phone number using a specific country code. After the desired phone number is selected, the phone number can be provisioned to a Sudo.

## Get Supported Countries

To get the list of supported countries, use the `getSupportedCountries()` method. The country code format currently supported is the two-letter format described in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

In sandbox mode, the "ZZ" country code is included to allow provisioning simulated phone numbers. Refer to the [Telephony Simulator](https://docs.sudoplatform.com/guides/telephony/simulator-and-the-zz-country-code) page for details.

{% tabs %}
{% tab title="Swift" %}

```swift
try! telephonyClient.getSupportedCountries { result in
    switch result {
    case .success(let countries):
        // countries: list of strings containing the country ISO codes
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
telephonyClient.getSupportedCountries { result ->
    when (result) {
        is Result.Success -> {
            // result.value.countries: list of strings containing 
            // the country ISO codes
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Each project in your Sudo Platform account can be configured to support a specific set of country codes. Your solutions engineer can assist you in selecting the desired country codes.
{% endhint %}

## Search Available Phone Numbers

A search for a phone number can be performed using either a country code, a country code plus phone number prefix (e.g., in the United States the prefix is called an "area code") or a latitude and longitude. A limit can be provided to ensure a maximum number of results are returned.

### By Country Only

To search for a phone number by country code, use the `searchAvailablePhoneNumbers()` method and provide the two-character ISO country code.

{% tabs %}
{% tab title="Swift" %}

```swift
// By country code
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US", 
                                                 limit: 5) { (result) in
    switch result {
    case .success(let searchResult):
        // searchResult: AvailablePhoneNumberResult (see below for details) 
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// By country code 

// val countryCode = "US"
telephonyClient.searchAvailablePhoneNumbers(countryCode) { result ->
    when (result) {
        is Result.Success -> {
            // result.value.numbers: PhoneNumberSearchResult
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

### By Country and Prefix

To search for a phone number by country code and prefix, use the `searchAvailablePhoneNumbers()` method and provide the two-character country code and prefix digits.

{% tabs %}
{% tab title="Swift" %}

```swift
//By area code
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US", 
                                                 prefix: "385",
                                                 limit: nil) { (result) in
    switch result {
    case .success(let searchResult):
        // searchResult: AvailablePhoneNumberResult (see below for details) 
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// By area code 

// val countryCode = "US"
// val areaCode = "385"
telephonyClient.searchAvailablePhoneNumbers(countryCode, areaCode) { result ->
    when (result) {
        is Result.Success -> {
            // result.value.numbers: PhoneNumberSearchResult (see below for details) 
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

### By Latitude and Longitude

To search for a phone number by country code and latitude/longitude, use the `searchAvailablePhoneNumbers()` method and provide the two-character country code and latitude/longitude. This function finds geographically close numbers within miles. Applies to only phone numbers in the US and Canada.

{% tabs %}
{% tab title="Swift" %}

```swift
// By lat/lng

// let country: String = "US"
// let lat: Double = 37.234332396
// let lng: Double = -115.80666344
try! client.searchAvailablePhoneNumbers(countryCode: country,
                                        latitude: lat,
                                        longitude: lng,
                                        limit: 5) { result in
    switch result {
    case .success(let searchResult):
        // searchResult: AvailablePhoneNumberResult (see below for details) 
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// By lat/lng

// val countryCode = "US"
// val latitude = "37.234332396"
// val longitude = "-115.80666344"
telephony.searchAvailablePhoneNumbers(countryCode, 
                                      latitude, 
                                      longitude) { result ->
    when (result) {
        is Result.Success -> {
            // result.value.numbers: PhoneNumberSearchResult (see below for details) 
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }

    this.latch.countDown()
}
```

{% endtab %}
{% endtabs %}

### Search Result

Both calls to `searchAvailablePhoneNumbers()` return a `AvailablePhoneNumberResult` (iOS) / `PhoneNumberSearchResult` (Android) on success. The result contains a list of available numbers and the country code / prefix used in the search.

The Telephony SDK uses the [E.164 phone number format](https://en.wikipedia.org/wiki/E.164) for all string representations of phone numbers.

{% tabs %}
{% tab title="Swift" %}

```swift
struct AvailablePhoneNumberResult {
    let numbers: [String] // List of numbers available in E.164 format
    let countryCode: String // Country code used for search
    let prefix: String? // Prefix used for search
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
data class PhoneNumberSearchResult (val id: String,
                                    val numbers: List<String>,
                                    val countryCode: String,
                                    val gps: AvailablePhoneNumberResult.Gps?,
                                    val prefix: String?,
                                    val state: PhoneNumberSearchState)
```

{% endtab %}
{% endtabs %}

## Provision Phone Number

After an available phone number is found, it can be provisioned to a Sudo using the `provisionPhoneNumber()` method. Provisioning a phone number to a Sudo makes it available to communicate with other phone numbers, such as sending and receiving SMS and MMS messages.

The Telephony SDK uses the [E.164 phone number format](https://en.wikipedia.org/wiki/E.164) for all string representations of phone numbers and this format is expected when provisioning a number.

{% tabs %}
{% tab title="Swift" %}

```swift
try! telephonyClient.provisionPhoneNumber(countryCode: "US", 
                                          phoneNumber: "+442071838750", 
                                          sudoId: "abc123") { result in
    switch result {
    case .success(let number):
        // number: PhoneNumber (see below for details)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// val countryCode = "US"
// val phoneNumber = "+442071838750"
// val sudoID = "abc123"
telephonyClient.provisionPhoneNumber(countryCode, phoneNumber, sudoID) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneNumber (see below for details)
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

### Phone Number

The `PhoneNumber` type is returned when a phone number is provisioned. This type is expected in other places where a phone number is used, such as sending an SMS/MMS message.

{% tabs %}
{% tab title="Swift" %}

```swift
public struct PhoneNumber {
    public enum State: Equatable {
        case complete
        case provisioning
        case deprovisioning
        case failed
        case unknown
    }

    public let id: String
    public let phoneNumber: String
    public let state: State
    public let version: Int
    public let created: Date
    public let updated: Date
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
data class PhoneNumber(
    val id: String,
    val phoneNumber: String,
    val state: PhoneNumberState,
    val version: Int,
    val created: Date,
    val updated: Date
)

public enum PhoneNumberState {
  PROVISIONING,
  FAILED,
  COMPLETE,
  DEPROVISIONING
}
```

{% endtab %}
{% endtabs %}

### Entitlements

Each user is allocated a limited number of phone numbers per Sudo. The current limit is 1 number per Sudo. In the future this value will be configurable from the Admin Console. If an attempt is made to provision a number in excess of the entitlements, and error will be returned from the SDK.

## De-Provision Phone Number

A previously provisioned phone number can be de-provisioned by using the `deletePhoneNumber()` method. This method expects an [E.164 phone number format](https://en.wikipedia.org/wiki/E.164) formatted phone number string. The phone number must have already been provisioned for this to succeed.

{% tabs %}
{% tab title="Swift" %}

```swift
try! telephonyClient.deletePhoneNumber(phoneNumber: "+442071838750") { result in
    switch result {
    case .success(let phoneNumber):
        // phoneNumber: E.164 formatted number
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// val phoneNumber: PhoneNumber
telephonyClient.deletePhoneNumber(phoneNumber.number) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneNumber
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Retrieving Existing Phone Numbers

Previously provisioned numbers can be retrieved using a phone number identifier or by retrieving all provisioned numbers.

### Using Phone Number ID

You can retrieve a previously provisioned phone numbers by using the `getPhoneNumber()` method.

{% tabs %}
{% tab title="Swift" %}

```swift
// let phoneNumber: PhoneNumber
try! telephonyClient.getPhoneNumber(id: phoneNumber.id) { (result) in
    switch result {
    case .success(let number):
        // number: PhoneNumber
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// val phoneNumber: PhoneNumber
telephonyClient.getPhoneNumber(phoneNumber.id) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneNumber
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

### All Provisioned Phone Numbers

To retrieve all provisioned phone numbers, use the `listPhoneNumbers()` method. This method supports paging using the `limit` and `nextToken` parameters, and optionally filters by sudo id.

{% tabs %}
{% tab title="Swift" %}

```swift
let sudoID: String
try! telephonyClient.listPhoneNumbers(sudoId: sudoId, limit: nil, nextToken: nil) { (result) in
    switch result {
    case .success(let listToken):
        // listToken: TelephonyListToken (see below for details)
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// val sudoID = "abc123"
telephonyClient.listPhoneNumbers(sudoId, null, null) { result ->
    when(result) {
        is Result.Success -> {
            // result.value: TelephonyListToken<PhoneNumber>
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}
```

{% endtab %}
{% endtabs %}

The result of the `listPhoneNumbers()` call is a TelephonyListToken as described below.

### Retrieve Multiple Phone Numbers Result

When multiple phone numbers are retrieved, for example through the `getPhoneNumbers()` method, a list token object is returned which includes a list of phone numbers and a paging token used to retrieve the next set of results.

{% tabs %}
{% tab title="Swift" %}

```swift
struct TelephonyListToken {
    let items: [PhoneNumber] // Phone numbers
    let nextToken: String? // Reference for next page

}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
data class TelephonyListToken<PhoneNumber>(
    val items: List<PhoneNumber>,
    val nextToken: String?
)
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/telephony/phone-numbers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.