Programmable Voice

Rent a Phone Number

No time to read?Watch this short video

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.

I. Rent Using Portal

Rent DID Using Portal

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

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

Click Rent New Number.

Select a state from the State dropdown menu.

Select an area code from the Area Code dropdown menu.

Click Search Availability.

When the Search Availability button is clicked, a list will populate below with phone numbers available for the selected state and area code.

Decide which phone number you would like to rent and click Rent Number.

A Rent Phone Number modal will appear.

Check Yes, I want to rent this Phone Number. Then click Rent Number.

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

Enable SMS/MMS Messaging for a DID

If you want to use the number for messaging, you need to enable SMS/MMS on the new phone number.

Open the SMS Enablement tab, click Edit.
In the Enabled dropdown menu, select true and click Update.

As soon as the messaging Status changes to enabled you are ready to send your first SMS message using the Portal.

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. Rent Using REST API

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

There are several ways to rent a phone number through CarrierX API:

if the phone number does not matter to you, you can rent a random DID using a POST request without any restrictions,
or send a POST request restricted by one or more filters and rent a phone number that matches these filters,
or, if you need a specific phone number, look for the available DIDs using a GET request and then rent the phone number you want with a POST request.

Rent a Random DID

If it does not matter to you which DID to rent, you can simply send a POST request with an empty body and not restricted by any filters:

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 a random available DID to you.

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": 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
}

Rent a DID Matching a Filter

If you want the rented phone number to belong to a certain state or area code, you can rent the DID right away with a single POST request restricted by filter.

For example, we want to rent a phone number in New York state with the 516 prefix. We will use a URL-encoded filter with the state equal to "NY" (state eq "NY") and the prefix equal to "516", i.e., phonenumber must contain "516" as a part of it (phonenumber ilike "%516%").

We will pass these arguments in the POST request with an empty body:

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids?filter=state+eq+%22NY%22+and+phonenumber+like+%22%25516%25%22' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The system will assign the first available phone number that matches the filters in the request to you.

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": 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
}

Get Available DIDs and Select One

If you want to rent a specific phone number, you can first see the list of available ones and select the one you want to rent.

Form a GET request. In the following example, we limit our results to one record, but you can specify the number of records you like. Refer to the Browse Available DIDs section in the Core API Reference for more information.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Like in the previous section, we want to search only for a phone number in New York state with the 516 prefix. We will use a URL-encoded filter with the state equal to "NY" (state eq "NY") and the prefix equal to "516", i.e., phonenumber must contain 516 as a part of it (phonenumber ilike "%516%"):

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&filter=state+eq+%22NY%22+and+phonenumber+like+%22%25516%25%22' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "active_capabilities": 4,
            "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": null,
            "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/available_dids?limit=1&filter=state+eq+%22NY%22+and+phonenumber+like+%22%25516%25%22&offset=1"
},
"total": null
}

Next we will take the phonenumber value 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 for more information.

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15162065575"}' \
-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:

{
    "active_capabilities": 4,
    "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
}

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):

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.

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.

Enable SMS/MMS Messaging

To be able to send SMS/MMS from a rented DID, messaging must be enabled for that DID. First, make sure that messaging is disabled on your DID.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3115c13-29dd-41b7-5dbc-89edbc59230d/messaging' \
-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:

{
    "enabled": false,
    "status": "disabled"
}

This response means that messaging is disabled on your DID. To enable it, you need to send the following POST request to the API.

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3125c23-29dd-41b7-5dbc-89edba59230d/messaging' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-binary '{"enabled": "true"}' \
-H 'Authorization: Bearer 5ebe03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 status code with information about the status of SMS/MMS enablement for this DID.

{
    "enabled": true,
    "status": "in_progress"
}

The first status the system returns is in_progress, meaning that the phone number is being processed for message enablement. Sometimes, this process may take up to several minutes. While the status is in_progress, no further messaging update requests are accepted for this DID. If you send a POST request to a DID with the in_progress status, a 409 error will be returned.

A bit later you may check the DID status by sending a GET request like the one above. A successful request will return a 200 status code along with a response that looks like the following:

{
    "enabled": true,
    "status": "enabled"
}

If the system returns the status failed, this means that some error has occurred in the process of messaging enablement. Please, contact technical support at support@carrierx.com in this case.

Please note, that to successfully enable messaging on a DID, make sure that it has SMS/MMS capabilities set. If no SMS/MMS capabilities are set for this DID, i.e. if this DID has only "capabilities": 4 (voice only), the request will return the 404 error.

Verify a Rented DID

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

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-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:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "active_capabilities": 7,
            "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
}

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

III. Next Steps

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

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

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