shell

Rent 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). Phone numbers can be assigned to endpoint trunk groups, and used to place and receive phone calls.

Renting a phone number through the CarrierX system gives you exclusive use of it until you release it. A released phone number is not immediately placed back into inventory. If you accidently delete a phone number and want to restore it or you want to order phone numbers in large blocks, contact technical support at support@carrierx.com.

I. Using the Portal

In this section, we will go over renting a phone number through the portal.

To rent a phone number through the portal, click on the Configure menu. Click Phone Numbers.

Click Menu

Click Rent new number.

Click Rent

Select a state from the State dropdown menu.

Select State

Select an area code from the Area Code dropdown menu.

Select Area

Click Search Availability.

Search Numbers

When the Search Availability button is clicked, a list will populate below with available phone numbers. Decide which phone number you would like to rent and click Rent Number.

Rent Number

A Rent Phone Number modal will appear. Check Yes, I want to rent this Phone Number. Then click Rent Number.

Confirm Rent

Once a phone number is rented, you will be able to view details and make edits.

Number Detail

We have finished renting a phone number through the portal. This phone number can now be assigned to an endpoint. In the next section, we will go over renting a phone number programmatically.

II. Using the REST API

In this section, we will go over programmatically searching for available phone numbers and renting one.

Form a GET request. In the following example, we limit our results to one record. Refer to the Browse Available DIDs section in the Core API Reference Guide for more information.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1' \
-u '[your_user_name]:[your_password]'


A successful response will return a 200 status code and a JSON object that looks like the following. We will use the value of phonenumber when building our new request to rent the phone number.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
        "callback_url": null,
        "capabilities": 7,
        "country_code": "USA",
        "did_group_sid": null,
        "did_sid": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
        "in_country_format": "(516) 206-5573",
        "international_format": "+1 516-206-5573",
        "locality": "NEW YORK",
        "name": "N/A",
        "partner_sid": null,
        "phonenumber": "15162065573",
        "price": "0.6",
        "state": "NY",
        "transformations": [],
        "trunk_group_sid": null
    }
],
"limit": 1,
"offset": 0,
"pagination": {
    "next": "https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&offset=1"
},
"total": null
}


2. Next we will take the value of phonenumber and construct a POST request. Additional values can be set when renting a DID. Refer to the Rent DID section in the Core API Reference Guide for more information.

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15162065575"}'
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "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
}


This rented phone number can now be assigned to an endpoint of your choosing. It can be updated using PATCH and PUT requests, as well as released by using a DELETE request.

We can also verify that we rented the phone number by making a GET request.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-u '[your_user_name]:[your_password]'


A successful request will return a 200 status code along with a response that looks like the following:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "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
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
      "next": "https://api.carrierx.com/core/v2/phonenumber/dids?limit=1&offset=1"
    },
    "total": 2
}

III. Next Steps

You have rented a phone number! Now you can associate a phone number with an endpoint. Refer to the left-side menu for links to the quick start guides and video tutorials for the different endpoints.

For more information, refer to the Endpoints and Phone Numbers sections of the Core API Reference Guide.

If you need to review some of the steps to rent a phone number, see our Rent a Phone Number video.