Rent DID

This request assigns a DID to a partner.

tip

Refer to our Rent a Phone Number quick start guide for a complete guide on how to rent phone numbers through CarrierX portal and API.

post	/phonenumber/dids

Sample

A sample POST request to assign a DID to a partner:

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15162065575", "callback_url":null}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the DID object:

{
    "active_capabilities": 4,    
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 31,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "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",
    "lata": null,
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "ocn": "251F",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "porting_pin": null,
    "price": "0.6",
    "state": "NY",
    "status": "assigned",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

Required Scopes

To create a DID object, the partner must have one of the following scopes enabled:

• phonenumber.manage
• phonenumber.create

Body Arguments

JSON representation of the fields and values of the DID object to be created.

No fields are required to rent a DID, an empty object can be passed.

If you do not specify a phone number, the system will assign the first available phone number to you.

If you want to rent a specific phone number, you need to pass it as a value for the phonenumber body attribute.

note

Note that once the phone number has been rented, it must be assigned a trunk group to be usable.

Query Arguments

Parameter	Data Type	Description
include_external	boolean	Determines whether the system should look for a phone number from an external provider in case it cannot locate a DID matching your filter criteria among the DIDs owned by CarrierX. Values accepted in this field are true and false. The default value is false. For more information about renting an external DID, refer to our Rent a Phone Number quick start guide.
filter	string	Restricts the phone number to be rented by some parameters (e.g., capabilities, state, country_code, etc.) and returns the first available phone number matching the filter when you do not specify any body arguments. 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. If include_external=true only the following combinations of filter parameters and operators are available in the result filter: country_code eq, which must be followed by a 3-letters country code, for example country_code eq "SWE". phonenumber like, which must be followed by a substring containing at least 3 digits. For example, [and] phonenumber like "%555%" or you can even give a specific DID in the filter: [and] phonenumber like "46500729289". capabilities, which must be followed by either bit or eq operator. Please note that external DIDs often have limited capabilities. In most cases, only SMS and voice are supported (capabilities bit 1, 2, and 4; and their combinations), so if you are using a capabilities filter with an external DID, you may need to make sure its number does not exceed 7, otherwise you may get very limited results.

Refer to this table to view all fields that appear in the DID object.

Response

The status of the DID you have ordered will depend on whether it is an internal DID from CarrierX or an external one.

In case it is an internal DID, it will immediately get the assigned status.

If you have ordered an external DID, its initial status is pending_assignment meaning that an external order for the DID has been created but not completed yet. After a while it changes to assigned. CarrierX will send you a callback on the external order completion, i.e. when a phone number changes its state from pending_assignment to assigned. The callback is identified as phonenumber_order and is configured by the partner on the Partner object. Please be aware that you cannot use your DID until its status changes to assigned.

note

Note, that as a rule, by default SMS/MMS messaging is disabled for all rented DIDs. Therefore, to be able to send SMS/MMS using the DID you have rented, you need to make sure that messaging is enabled, and if not, enable it by sending a POST request to the API.