1. References
  2. Management API
  3. PhoneNumbers
Rate this page:

PhoneNumbers

Methods

AttachPhoneNumber

Copy URL

Attach the phone number to the account. Note that phone numbers of some countries may require additional verification steps.

Please note that when you purchase a phone number, we reserve the subscription fee and taxes for the upcoming month. Read more in the Billing page.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
AttachPhoneNumber example
Copy

AttachPhoneNumber example

Attach a US phone number to the account 1.

Parameters

Returns

BindPhoneNumberToApplication

Copy URL

Bind the phone number to the application or unbind the phone number from the application. You should specify the application_id or application_name if you specify the rule_name.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
BindPhoneNumberToApplication example
Copy

BindPhoneNumberToApplication example

Bind the phone 1 to the application 1.

Parameters

  • application_id:

    number

    The application ID

  • application_name:

    string

    The application name that can be used instead of application_id

  • bind:

    boolean

    Optional
    Defaults on:  true

    Whether to bind or unbind (set true or false respectively)

  • phone_id:

    intlist

    The phone ID list separated by semicolons (;). Use the 'all' value to select all phone ids

  • phone_number:

    stringlist

    The phone number list separated by semicolons (;) that can be used instead of phone_id

  • rule_id:

    number

    Optional

    The rule ID

  • rule_name:

    string

    Optional

    The rule name that can be used instead of rule_id

Returns

  • result:

    number

    1

DeactivatePhoneNumber

Copy URL

Deactivates the phone number.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
DeactivatePhoneNumber example
Copy

DeactivatePhoneNumber example

Deactivate the phone 1.

Parameters

  • phone_id:

    intlist

    The phone ID list separated by semicolons (;). Use the 'all' value to select all phone ids

  • phone_number:

    stringlist

    The phone number list separated by semicolons (;) that can be used instead of phone_id

Returns

  • result:

    number

    1

GetAccountPhoneNumberCountries

Copy URL

Gets all countries where the specific account has phone numbers.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
Supervisor
Accountant
Support
Payer
Verification
GetAccountPhoneNumberCountries example
Copy

GetAccountPhoneNumberCountries example

Get the countries where the account with id = 1 has phone numbers attached to the application with id = 1.

Parameters

  • application_id:

    intlist

    Optional

    The application ID list separated by semicolons (;) to filter

Returns

  • result:

    [string]

    Array of country codes

GetActualPhoneNumberRegion

Copy URL

Get actual info on the country region of the phone numbers. The response also contains the info about multiple numbers subscription for the child accounts.

GetActualPhoneNumberRegion example
Copy

GetActualPhoneNumberRegion example

Get the Germany region of the phone numbers.

Parameters

  • country_code:

    string

    The country code

  • country_state:

    string

    Optional

    The country state code (example: AL, CA, … )

  • locale:

    string

    Optional

    The 2-letter locale code. Supported values are EN, RU

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories method

  • phone_region_id:

    number

    The phone region ID to filter

Returns

GetNewPhoneNumbers

Copy URL

Gets the new phone numbers.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
GetNewPhoneNumbers example
Copy

GetNewPhoneNumbers example

Get the two new fixed Russian phone numbers at max.

Parameters

  • count:

    number

    Optional
    Defaults on:  20

    The max returning record count

  • country_code:

    string

    The country code

  • country_state:

    string

    Optional

    The country state. See the GetPhoneNumberCategories and GetPhoneNumberCountryStates functions

  • offset:

    number

    Optional
    Defaults on:  0

    The first N records are skipped in the output

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories function

  • phone_number_mask:

    string

    Optional

    The phone number searching mask. Asterisk represents zero or more occurrences of any character

  • phone_region_id:

    number

    The phone region ID. See the GetPhoneNumberRegions method

Returns

  • count:

    number

    The returned phone count

  • result:

    [NewPhoneInfoType]

  • total_count:

    number

    The total found phone count

GetPhoneNumberCategories

Copy URL

Gets the phone number categories.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
Payer
GetPhoneNumberCategories example
Copy

GetPhoneNumberCategories example

Get the all phone number categories.

Parameters

  • country_code:

    stringlist

    Optional

    Country code list separated by semicolons (;)

  • locale:

    string

    Optional

    The 2-letter locale code. Supported values are EN, RU

  • sandbox:

    string

    Optional

    Flag allows you to display phone number categories only of the sandbox, real or all .The following values are possible: 'all', 'true', 'false'

Returns

GetPhoneNumberCountryStates

Copy URL

Gets the phone number country states.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
Payer
GetPhoneNumberCountryStates example
Copy

GetPhoneNumberCountryStates example

Get the USA states.

Parameters

  • country_code:

    string

    The country code

  • country_state:

    string

    Optional

    The country state code (example: AL, CA, … )

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories function

Returns

GetPhoneNumberRegions

Copy URL

Get the country regions of the phone numbers. The response also contains the info about multiple numbers subscription for the child accounts.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
Payer
GetPhoneNumberRegions example
Copy

GetPhoneNumberRegions example

Get the Russian regions of the phone numbers.

Parameters

  • country_code:

    string

    The country code

  • country_state:

    string

    Optional

    The country state code (example: AL, CA, … )

  • locale:

    string

    Optional

    The 2-letter locale code. Supported values are EN, RU

  • omit_empty:

    boolean

    Optional
    Defaults on:  true

    Whether not to show all the regions (with and without phone numbers in stock)

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories method

  • phone_region_code:

    string

    Optional

    The region phone prefix to filter

  • phone_region_id:

    number

    Optional

    The phone region ID to filter

  • phone_region_name:

    string

    Optional

    The phone region name to filter

Returns

GetPhoneNumbers

Copy URL

Gets the account phone numbers.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
Supervisor
Accountant
Support
Payer
GetPhoneNumbers example
Copy

GetPhoneNumbers example

Get two attached phone numbers.

Parameters

  • application_id:

    number

    Optional

    The application ID

  • application_name:

    string

    Optional

    The application name that can be used instead of application_id

  • auto_charge:

    boolean

    Optional

    Whether the auto_charge flag is enabled

  • can_be_used:

    boolean

    Optional

    Whether a not verified account can use the phone

  • canceled:

    boolean

    Optional

    Whether the subscription is cancelled to filter

  • child_account_id:

    intlist

    Optional

    The child account ID list separated by semicolons (;). Use the 'all' value to select all child accounts

  • children_phones_only:

    boolean

    Optional
    Defaults on:  false

    Whether to get the children phones only

  • count:

    number

    Optional
    Defaults on:  100

    The max returning record count

  • country_code:

    stringlist

    Optional

    The country code list separated by semicolons (;)

  • deactivated:

    boolean

    Optional

    Whether the subscription is frozen to filter

  • from_phone_next_renewal:

    date

    Optional

    The UTC 'from' date filter in format: YYYY-MM-DD

  • from_phone_purchase_date:

    timestamp

    Optional

    The UTC 'from' date filter in 24-h format: YYYY-MM-DD HH:mm:ss

  • from_unverified_hold_until:

    date

    Optional

    Unverified phone hold until the date (from …) in format: YYYY-MM-DD

  • is_bound_to_application:

    boolean

    Optional

    Whether the phone number bound to an application

  • is_bound_to_rule:

    boolean

    Optional

    Whether the phone number is bound to some rule

  • offset:

    number

    Optional
    Defaults on:  0

    The first N records are skipped in the output

  • order_by:

    string

    Optional

    The following values are available: 'phone_number' (ascent order), 'phone_price' (ascent order), 'phone_country_code' (ascent order), 'deactivated' (deactivated first, active last), 'purchase_date' (descent order), 'phone_next_renewal' (ascent order), 'verification_status', 'unverified_hold_until' (ascent order), 'verification_name'

  • phone_category_name:

    string

    Optional

    The phone category name. See the GetPhoneNumberCategories method

  • phone_id:

    intlist

    Optional

    The particular phone ID to filter

  • phone_number:

    stringlist

    Optional

    The phone number list separated by semicolons (;) that can be used instead of phone_id

  • phone_region_name:

    stringlist

    Optional

    The region names list separated by semicolons (;)

  • phone_template:

    string

    Optional

    The phone number start to filter

  • rule_id:

    intlist

    Optional

    The rule ID list separated by semicolons (;)

  • rule_name:

    stringlist

    Optional

    The rule names list separated by semicolons (;). Can be used only if application_id or application_name is specified

  • sandbox:

    string

    Optional

    Flag allows you to display only the numbers of the sandbox, real numbers, or all numbers. The following values are possible: 'all', 'true', 'false'

  • to_phone_next_renewal:

    date

    Optional

    The UTC 'to' date filter in format: YYYY-MM-DD

  • to_phone_purchase_date:

    timestamp

    Optional

    The UTC 'to' date filter in 24-h format: YYYY-MM-DD HH:mm:ss

  • to_unverified_hold_until:

    date

    Optional

    Unverified phone hold until the date (… to) in format: YYYY-MM-DD

  • verification_name:

    string

    Optional

    The required account verification name to filter

  • verification_status:

    stringlist

    Optional

    The account verification status list separated by semicolons (;). The following values are possible: REQUIRED, IN_PROGRESS, VERIFIED

Returns

  • count:

    number

    The returned phone count

  • result:

    [AttachedPhoneInfoType]

    Phone numbers info

  • total_count:

    number

    The total found phone count

GetPhoneNumbersAsync

Copy URL

Gets the asyncronous report regarding purchaced phone numbers.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
Supervisor
Accountant
Support
Payer
PhoneNumberManager
GetPhoneNumbersAsync example
Copy

GetPhoneNumbersAsync example

Get two attached phone numbers.

Parameters

  • with_header:

    boolean

    Optional
    Defaults on:  true

    Whether to get a CSV file with the column names

Returns

  • result:

    number

    The report ID (async mode)

IsAccountPhoneNumber

Copy URL

Checks if the phone number belongs to the authorized account.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
Supervisor
Accountant
Support
Payer
IsAccountPhoneNumber example
Copy

IsAccountPhoneNumber example

Check if the phone number belongs to the account.

Parameters

  • phone_number:

    string

    Phone number to check in the international format without +

Returns

  • result:

    boolean

    Whether the number belongs to the account

SetPhoneNumberInfo

Copy URL

Set the phone number information.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Accountant
SetPhoneNumberInfo example
Copy

SetPhoneNumberInfo example

Enable the auto charging.

Parameters

  • incoming_sms_callback_url:

    string

    Optional

    If set, the callback of an incoming SMS is sent to this url, otherwise, it is sent to the general account URL

  • phone_id:

    intlist

    The phone ID list separated by semicolons (;). Use the 'all' value to select all phone ids

  • phone_number:

    stringlist

    The phone number list separated by semicolons (;) that can be used instead of phone_id

Returns

  • result:

    number

    1