Skip to main content

Browse Available DIDs

This request returns a pool of rentable phone numbers.

get /phonenumber/available_dids
get /dids/inventorydeprecated

Sample​

A sample GET request to get available DIDs matching the criteria in the request URL:

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

Response​

200 status code with a list of available DID objects:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "active_capabilities": 4,
            "attributes": {},
            "callback_url": null,
            "campaign_sid": null,
            "capabilities": 7,
            "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
            "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",
            "lata": null,
            "locality": "NEW YORK",
            "lrn_sid": null,
            "name": "N/A",
            "ocn": "251F",
            "partner_sid": null,
            "phonenumber": "15162065573",
            "porting_pin": null,
            "price": "0.6",
            "state": "NY",
            "status": "available",
            "string_key_1": null,
            "string_key_2": null,
            "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
}

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Required Scopes​

To get information about rentable numbers the partner must have one of the following scopes enabled:

  • phonenumber.manage
  • phonenumber.read

Filtering by Location​

CarrierX allows you to filter the available phone numbers by their geographical location and area codes. Refer to the table below to see the parameters which you can use to do this.

ParameterDescriptionSyntaxExamples
latlngUse this option to search for the phone numbers located closer to the area described by geographical coordinates specified.phonenumber nearby latlng:<latitude,longitude>filter=phonenumber+nearby+latlng%3A40.801912%2C-73.9681657
npaUse this option to search for the phone numbers located closer to the area associated with the NANP area code specified. See tip below.phonenumber nearby npa:<npa>filter=phonenumber+nearby+npa%3A516
zipUse this option to search for the phone numbers located closer to the area associated with the ZIP code specified.phonenumber nearby zip:<zip>filter=phonenumber+nearby+zip%3A10025
tip

The filter phonenumber nearby npa is a geographical search and may return numbers outside the NPA specified but geographically nearby or in an overlay NPA. To search within a specific area code, use phonenumber like "1<npa>%". The percent symbol, %, is a wildcard, so 1<npa>% says anything that starts with 1<npa>. For example, to find numbers in the 415 area code use:

phonenumber like "1415%"

Query Arguments​

ParameterData TypeDescription
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.
If include_external=true, Pagination is not supported; the offset must be 0, the limit is set by the user but the number of records in the response depends on the external provider. The system will try to offer a sufficient amount of DIDs satisfying the request criteria from its internal database first, and if this amount is not sufficient, then the system will send a request to the external DIDs provider. Note that the maximum number of external DIDs shown per request is 10. Internally available phone numbers are shown in the request results list first, followed by external numbers.
Important: if include_external=true the request must contain a filter with the country_code parameter.
If include_external=true only the following combinations of filter parameters and operators are allowed in the result filter:

  • country_code eq required, 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.