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
pageNo

3

Fetch the specified results page. The default is 1.

limitNo25The number of results per page. The default is 10.

You will receive this standard paginated response:

Parameter
Example
Description
page 3The current fetched page.
limit25The number of results per page.
pageCount150The total number of pages.
resourcesArray of number resourcesSee 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
id305Dedicated number ID.
phone 447860021130Dedicated phone number.
countrycountry resourceSee country description below.
statusA

Number status:

  • U for Unused. No messages have been sent from (or received to) this number.
  • A for Active.
purchasedAt 2014-10-02T11:07:04+0000Time when the dedicated number was purchased.
expireAt 2014-10-02T11:07:04+0000Dedicated number subscription expiration time.
useruser resourceUser to which the dedicated number is assigned.

Country resource format

The country resource contains the following fields:

Parameter
Example
Description
id

GB

FR

Two-letter ISO country ID.
name NorwayFull 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
countryYes

GB
for Great Britain

Two-letter dedicated number country ISO code.

prefixNo447155Desired 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.4Dedicated number monthly fee for this country. Returned in current account currency.
numbersarray of stringsArray 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
phoneYes

447860021130

Dedicated phone number.

countryYes GB Country code phone number.
userIdYes5501Assigned 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 305New dedicated number ID.
href/api/v2/numbers/304Link 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.