Manage Dedicated Numbers
extmagic currently offers dedicated numbers in over 25 countries and growing. In mobile communication, it is convenient to use a local number for different campaigns. Your customers will then be able to reply to you, or may even text you first. Promote your dedicated number as your company’s contact point.
Get all your dedicated numbers
To get all your purchased dedicated numbers use:
GET /api/v2/numbers
with these parameters:
|
Name
|
Required?
|
Example
|
Description
|
|---|---|---|---|
| page | No |
|
Fetch the specified results page. The default is 1. |
| limit | No | 25 |
The number of results per page. The default is 10. |
You will receive this standard paginated response:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| page |
3
|
The current fetched page. |
| limit | 25 |
The number of results per page. |
| pageCount | 150 |
The total number of pages. |
| resources | Array of number resources | See next section for number resource format details. |
Get the details of a specific dedicated number
To get a single dedicated number, use:
GET /api/v2/numbers/{id}
where id is a dedicated number ID. Note, this command has no parameters.
The response format you will receive is:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| id | 305 |
Dedicated number ID. |
| phone |
447860021130
|
Dedicated phone number. |
| country | country resource | See country description below. |
| status | A |
Number status:
|
| purchasedAt |
2014-10-02T11:07:04+0000
|
Time when the dedicated number was purchased. |
| expireAt |
2014-10-02T11:07:04+0000
|
Dedicated number subscription expiration time. |
| user | user resource | User to which the dedicated number is assigned. |
Country resource format
The country resource contains the following fields:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| id |
|
Two-letter ISO country ID. |
| name |
Norway
|
Full country name. |
Find dedicated numbers available for purchase
To find dedicated numbers available for purchase, use:
GET /api/v2/numbers/available
with the parameters:
|
Name
|
Required?
|
Example
|
Description
|
|---|---|---|---|
| country | Yes |
|
Two-letter dedicated number country ISO code. |
| prefix | No | 447155 |
Desired number prefix. Should include country code (i.e. 447 for UK phone number format). Leave blank to get all the available numbers for the specified country. |
If successful, you will receive a response in the following format:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| price |
2.4
|
Dedicated number monthly fee for this country. Returned in current account currency. |
| numbers | array of strings | Array of phone number strings. |
Buy a new dedicated number
To buy a dedicated number, you first need to find an available number matching your criteria using the previous command.
GET /api/v2/numbers/available
Then use:
POST /api/v2/numbers
with the following parameters:
|
Name
|
Required?
|
Examples
|
Description
|
|---|---|---|---|
| phone | Yes |
|
Dedicated phone number. |
| country | Yes |
GB
|
Country code phone number. |
| userId | Yes | 5501 |
Assigned dedicated number. This number will be available for this account only. You cannot transfer numbers between sub-accounts. |
If successful, you will receive the standard link response:
|
Parameter
|
Example
|
Description
|
|---|---|---|
| id |
305
|
New dedicated number ID. |
| href | /api/v2/numbers/304 |
Link to dedicated number. |
Cancel a dedicated number
To cancel a subscription for a dedicated number, use:
DELETE /api/v2/numbers/{id}
where id is the dedicated number ID. Note, this command has no parameters. If successful, the command will return the standard delete response (204 No Content), otherwise the standard error response will be returned.
The next step
Now you’ve learned how to manage dedicated virtual numbers via Textmagic API, please continue to the next section, where we will show you how to manage alphanumeric Sender IDs.
