Rent a Phone Number
In this guide, you will learn how to rent a phone number. A rentable phone number is also called a DID (Direct Inward Dialing).
There are two ways to set up a phone number:
- through CarrierX Portal via the user interface
- programmatically via the CarrierX API
Depending on your preferences you can select either of them.
Rent a Phone Number Using Portal
Let's rent a phone number through the Portal.
In the left-hand navigation menu, select CONFIGURE > Phone Numbers. Then, in the top-right corner, click the Rent New Number button.
Select a Country of your phone number. Optionally, if you would like to select a specific geography or an area code, select a State and Area Code.
Click the Search Availability button.
When the Search Availability button is clicked, the phone numbers list below will populate with numbers available for the selected state, area code and capabilities.
Select a phone number and click the Rent Number button.
The Rent Phone Number modal will appear. Check Yes, I want to rent this Phone Number and click the Rent Number button.
To be able to use a rented phone number to make and receive calls, you first need to assign a trunk group to that number.
We have rented a phone number through the portal. In the next section, we will go over renting a phone number programmatically.
Rent a Phone Number Using REST API
In this Quick Start, we will rent a random phone number using a POST request.
This is where you are going to need the [security token] you have created earlier.
To rent a phone number, send a POST request with an empty body to the /phonenumber/dids endpoint.
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
The system will assign you a random available phone number (aka DID).
A successful request will return a 200 status code along with a response that looks like the following:
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"capabilities": 31,
"country_code": "USA",
"did_group_sid": null,
"did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
"in_country_format": "(516) 206-5575",
"international_format": "+1 516-206-5575",
"locality": "NEW YORK",
"name": "N/A",
"partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
"phonenumber": "15162065575",
"price": "0.6",
"state": "NY",
"transformations": [],
"trunk_group_sid": null
}
To be able to use a rented phone number to make and receive calls, you first need to assign a trunk group to that number.
Get and Order Available DIDs from an External Provider
In addition to its own DIDs, CarrierX allows you to order phone numbers from external providers. This option may be useful when you need to rent international numbers. CarrierX has an inventory of international numbers. However, for greater coverage you have the option to rent phone numbers from external providers. This provides better flexibility and coverage.
For example, you would like to search for a Swedish phone number that contains '123' and you would like to include external providers in your search. We will use a URL-encoded filter with the country_code equal to Sweden (country_code eq "SWE"), the phone number we are looking for must contain '123' as its part (phonenumber like "%123%"), we would like to include phone numbers from external providers in our search results (include_external=true) and we would like to order our search results by phone numbers (order=phonenumber):
If include_external=true the country_code parameter is required except for the case when you pass a specific DID as the phonenumber body argument.
curl -X GET \
'http://api-carrierx.int/core/v2/phonenumber/available_dids/?filter=country_code+eq+%22SWE%22+and+phonenumber+like+%22%25123%25%22&include_external=true&order=phonenumber' \
-H 'Authorization:Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
A successful response will return a 200 status code and a JSON object with a list of available phone numbers in Sweden ordered by phone number and containing the '123' sequence of digits in them. Phone numbers available from CarrierX are shown in the results list first, with the available status, numbers from external providers follow next.
To rent a DID from an external provider through CarrierX, you can set the include_external query argument to true, take the value of a phonenumber you like and send a request like this one:
curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids?include_external=true' \
-H 'Content-Type: application/json' --data-binary '{"phonenumber":"46501818082"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
A successful request will return a 200 status code along with a response that looks like the following. The status of the DID you have ordered will be either assigned or pending_assignment if an external order for the DID has been created but not completed yet.
{
"active_capabilities": 4,
"attributes": {},
"callback_url": null,
"capabilities": 4,
"classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
"country_code": "SWE",
"did_group_sid": null,
"did_sid": "32fbe218-db53-42ad-91b7-a4b25e2c8rcf",
"in_country_format": "0501-81 80 82",
"international_format": "+46 501 81 80 82",
"locality": null,
"lrn_sid": null,
"name": "N/A",
"partner_sid": "a13c384d-cf78-48fd-ab8b-1053b49291ba",
"phonenumber": "46501818082",
"price": "0.66",
"state": null,
"status": "pending_assignment",
"string_key_1": null,
"string_key_2": null,
"transformations": [],
"trunk_group_sid": null
}
Note: In case you get a 409 error code, this means the external request cannot be temporarily processed. Please try to send your request once again later.
If you prefer to rent a DID matching specific filter criteria, e.g. a Swedish number but the number itself is not important (you are ready to rent any random number from Sweden), then you can set the include_external query argument to True and leave your POST request without the phonenumber body argument. In this case the system will first try to find and rent a random DID matching your filter criteria from the pool of DIDs owned by CarrierX and if no such DID is located, the system will order a DID from an external provider.
To be able to use a rented phone number to make and receive calls, you first need to assign a trunk group to that number.
Next Steps
You have rented a phone number! The next step is to assign a trunk group to that phone number so you can start making calls.