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

  • 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

  • application_id:

    number

    The application ID

  • application_name:

    string

    The application name that can be used instead of application_id

  • rule_id:

    number

    Optional

    The rule ID

  • rule_name:

    string

    Optional

    The rule name that can be used instead of rule_id

  • bind:

    boolean

    Optional
    Defaults on:  true

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

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

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

  • 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

  • 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

Returns

  • result:

    number

    1

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

  • 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

  • application_id:

    number

    Optional

    The application ID

  • application_name:

    string

    Optional

    The application name that can be used instead of application_id

  • is_bound_to_application:

    boolean

    Optional

    Whether the phone number bound to an application

  • phone_template:

    string

    Optional

    The phone number start to filter

  • country_code:

    stringlist

    Optional

    The country code list separated by semicolons (;)

  • phone_category_name:

    string

    Optional

    The phone category name. See the GetPhoneNumberCategories method

  • canceled:

    boolean

    Optional

    Whether the subscription is cancelled to filter

  • deactivated:

    boolean

    Optional

    Whether the subscription is frozen to filter

  • auto_charge:

    boolean

    Optional

    Whether the auto_charge flag is enabled

  • from_phone_next_renewal:

    date

    Optional

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

  • to_phone_next_renewal:

    date

    Optional

    The UTC 'to' 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

  • to_phone_purchase_date:

    timestamp

    Optional

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

  • 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

  • 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

  • from_unverified_hold_until:

    date

    Optional

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

  • to_unverified_hold_until:

    date

    Optional

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

  • can_be_used:

    boolean

    Optional

    Whether a not verified account can use the phone

  • 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'

  • 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'

  • count:

    number

    Optional
    Defaults on:  100

    The max returning record count

  • offset:

    number

    Optional
    Defaults on:  0

    The first N records are skipped in the output

  • phone_region_name:

    stringlist

    Optional

    The region names list separated by semicolons (;)

  • 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

  • is_bound_to_rule:

    boolean

    Optional

    Whether the phone number is bound to some rule

Returns

  • result:

    [AttachedPhoneInfoType]

    Phone numbers info

  • total_count:

    number

    The total found phone count

  • count:

    number

    The returned phone count

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

  • country_code:

    string

    The country code

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories function

  • country_state:

    string

    Optional

    The country state. See the GetPhoneNumberCategories and GetPhoneNumberCountryStates functions

  • phone_region_id:

    number

    The phone region ID. See the GetPhoneNumberRegions method

  • count:

    number

    Optional
    Defaults on:  20

    The max returning record count

  • offset:

    number

    Optional
    Defaults on:  0

    The first N records are skipped in the output

Returns

  • result:

    [NewPhoneInfoType]

  • total_count:

    number

    The total found phone count

  • count:

    number

    The returned 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 (;)

  • 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'

  • locale:

    string

    Optional

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

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

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories function

  • country_state:

    string

    Optional

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

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

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories method

  • country_state:

    string

    Optional

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

  • omit_empty:

    boolean

    Optional
    Defaults on:  true

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

  • phone_region_id:

    number

    Optional

    The phone region ID to filter

  • phone_region_name:

    string

    Optional

    The phone region name to filter

  • phone_region_code:

    string

    Optional

    The region phone prefix to filter

  • locale:

    string

    Optional

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

Returns

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

  • phone_category_name:

    string

    The phone category name. See the GetPhoneNumberCategories method

  • country_state:

    string

    Optional

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

  • phone_region_id:

    number

    The phone region ID to filter

  • locale:

    string

    Optional

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

Returns

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