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

3

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:

  • U for Unused. No messages have been sent from (or received to) this number.
  • A for Active.
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

GB

FR

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

GB
for Great Britain

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

447860021130

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.