Rent a Phone Number

A detailed guide to renting phone numbers through the CarrierX portal and programmatically.

Overview


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 .



Rent a Number Through the Portal


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

1. Click on the Configure menu. Click Phone Numbers .



2. Click Rent new number .



3. Select a state from the State dropdown menu.



4. Select an area code from the Area Code dropdown menu.



5. Click Search Availability .



6. 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 .



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



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



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.



Rent a Number Programmatically


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

1. 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 response will return a 200 status code and a JSON object 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 response will return a 200 status code and a JSON object 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
}

If the phone number was rented properly, it should now show up in the GET request response.