LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Schedule Send
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  • Get Supported Countries
  • Search Available Phone Numbers
  • By Country Only
  • By Country and Prefix
  • By Latitude and Longitude
  • Search Result
  • Provision Phone Number
  • Phone Number
  • Entitlements
  • De-Provision Phone Number
  • Retrieving Existing Phone Numbers
  • Using Phone Number ID
  • All Provisioned Phone Numbers
  • Retrieve Multiple Phone Numbers Result
  1. Guides
  2. Telephony

Manage Phone Numbers

PreviousIntegrate the Telephony SDKNextText Messaging

Last updated 3 years ago

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 .

In sandbox mode, the "ZZ" country code is included to allow provisioning simulated phone numbers. Refer to the page for details.

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
    }
}
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
        }
    }
}

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.

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.

// 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
    }
}
// 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
        }
    }
}

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.

//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
    }
}
// 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
        }
    }
}

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.

// 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
    }
}
// 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()
}

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.

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
}
data class PhoneNumberSearchResult (val id: String,
                                    val numbers: List<String>,
                                    val countryCode: String,
                                    val gps: AvailablePhoneNumberResult.Gps?,
                                    val prefix: String?,
                                    val state: PhoneNumberSearchState)

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.

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
    }
}
// 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
        }
    }
}

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.

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
}
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
}

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

try! telephonyClient.deletePhoneNumber(phoneNumber: "+442071838750") { result in
    switch result {
    case .success(let phoneNumber):
        // phoneNumber: E.164 formatted number
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}
// val phoneNumber: PhoneNumber
telephonyClient.deletePhoneNumber(phoneNumber.number) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneNumber
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}

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.

// 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
    }
}
// val phoneNumber: PhoneNumber
telephonyClient.getPhoneNumber(phoneNumber.id) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: PhoneNumber
        }
        is Result.Error -> {
            // result.throwable: telephonysdk.Result.Error
        }
    }
}

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.

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
    }
}
// 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
        }
    }
}

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.

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

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

The Telephony SDK uses the for all string representations of phone numbers.

The Telephony SDK uses the for all string representations of phone numbers and this format is expected when provisioning a number.

A previously provisioned phone number can be de-provisioned by using the deletePhoneNumber() method. This method expects an formatted phone number string. The phone number must have already been provisioned for this to succeed.

🗺️
ISO 3166-1 alpha-2
Telephony Simulator
E.164 phone number format
E.164 phone number format
E.164 phone number format