Core API Reference

The CarrierX service offers a RESTful API that can be used to rent phone numbers, enable SMS for applications, support SIP trunking, and provision full-featured application endpoints.

Using the REST API

This section describes how to obtain credentials to use the API, what types of requests the system recognizes, and the format of the responses. It also holds reference information about pagination, filtering, and callbacks.

Using Postman

This documentation contains cURL commands that you will run in your terminal. Rather than use these commands, you can explore the API using Postman, a stand-alone client with a user-friendly interface. Postman is widely used for API development and allows you to test requests.

You will need to download the Postman client to your computer. To do so, visit the Postman website and click Download. Click Run in Postman to import this collection to the Postman app.

Run in Postman

Main Conventions

The following conventions are used in the sections, which contain the tables with objects attributes, their types, and descriptions:

create The attribute can be set when the user creates the object using the POST method.
update The attribute can be modified when the user updates the object using either PATCH or PUT methods.
read only The attribute is set by the system and the user can neither set nor modify it.
admin The attribute can be set or modified using the administrator API only. In the case the attribute is read only, it is visible to the partners with access to the administrator API, and hidden from other partners.
preview The attribute is part of the feature that is still in development and is not recommended to use in production.

Authentication

The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint login and password values are listed in the returned JSON object.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The credentials of a specific endpoint are found in the properties attribute of the nested object. Locate the login and password values.

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 1
}

All CarrierX API requests require authentication. The first step to using CarrierX API is obtaining a CarrierX account and gaining credentials. To do so, please submit a request through our Contact Us page.

Currently, CarrierX API requests use two types of authentication:

With the credentials you receive from CarrierX team, you can gain access to the Portal, where you will be able to create a security token. The security token allows you to work with the Core API and retrieve the endpoint login credentials for Conference, FlexML, and Mediator.

While the system allows request authentications for any users registered with CarrierX, the specific requests are limited by the scopes associated with the OAuth token that you use for the requests. This means that you might be eligible to make requests to CarrierX API, but not authorized to make a specific request, e.g., you can only view objects but not allowed to create, modify, or delete them.

You can create OAuth tokens with restricted access permissions (scopes) if you need that for a specific application. Refer to the Generate OAuth Bearer Token section for more details on this.

Prior to making requests to a Conference, FlexML, or Mediator endpoint, you need to create an application endpoint. Refer to the Configure an Application Endpoint quick start guide for step-by-step instructions on creating an endpoint.

Requests

Sample request to create Conference endpoint

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The requests in CarrierX API are made using the standard REST notation, typical for web services.

A simplest request will have the following structure:

All the above elements are required for all CarrierX API requests.

Other request may have additional structure elements which include:

Request URL

The usual path to the API objects includes the base URL to the API used with the object (Core API base URL for the objects used throughout the CarrierX products, or specific API base URLs used for FlexML, Mediator, or Conference), and the path to the object collections and the object items.

If the action targets the specific object, the path to it will include the object secure ID (SID), which allows to distinguish the targeted object from the other ones in the same collection.

The system only accepts HTTPS requests, and not HTTP requests.

Request Methods

CarrierX API uses five main verbs (methods) of REST over HTTP for the requests: POST, GET, PUT, PATCH, and DELETE. These methods are used to create the objects, get the information about the objects, modify the objects, and delete them.

CarrierX partners need to have special permissions (or scopes) to use API methods on various objects. Refer to the available_scopes table for the complete list of the scopes that define the partner’s permissions on objects and collections.

POST

Sample POST request that creates a trunk

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The POST method is used to create new objects. When you create a new object, you usually need to specify at least some of the attributes for the object to be created in the request payload.

The successful POST request will return a 200 response with the serialized JSON copy of the created object.

GET

Sample GET request that returns the currently logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The GET method is used to view the information about the existing objects and their collections.

Generic GET requests return the list of all the objects (or collections) available for the request sent. Most of such GET requests can be used together with Pagination, Result Filtering, and Field Filtering.

GET requests aimed at a specific object require to use the object secure ID to be included as a part of the request path, and return the information about the specified object only. Most of such GET requests can be used together with Field Filtering.

The successful GET request will return a 200 response with the serialized JSON copy of the requested objects (or specific object).

PATCH/PUT

Sample PATCH request that modifies or adds a new name record of the nested attributes object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"New Partner Name"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

{
    "attributes": {
        "name": "New Partner Name"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request that adds a new name2 record of the nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name2":"New Partner Name 2"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the modified nested object

{
    "attributes": {
        "name": "New Partner Name"
        "name2": "New Partner Name 2"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request that modifies the entire nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b?nested_objects=replace' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name3":"New Partner Name 3"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

{
    "attributes": {
        "name3": "New Partner Name 3"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

The PATCH/PUT methods are both used to modify the existing objects and their attributes. The difference between them is explained below.

PATCH is used to modify only some of the object attributes and does not require to send the entire object in the request payload. Only the attributes and their values that need to be modified can be sent in the request body.

Objects can have a complex structure and can contain other objects as part of them, i.e., nested inside them. When you use PATCH and want to modify the nested objects, PATCH follows the below rules to define what must be updated and how:

  1. If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the PATCH request. The other nested object records will remain unmodified.

  2. If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.

  3. If the existing nested object contains the same record and the value of the incoming record is null, then the existing record will be removed. The other nested object records will remain unmodified.

  4. If the PATCH request contains nested_objects=replace as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).

PUT is used to modify the complete object and require to send the entire object (together with the nested objects, if there are any) in the request payload.

Both PATCH and PUT requests are aimed at a specific object and require the object secure ID as a part of the request path.

The successful PATCH/PUT request will return a 200 response with the serialized JSON copy of the modified object.

DELETE

Sample DELETE request that deletes an endpoint

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The DELETE method is used to delete the object targeted by its secure ID.

The successful DELETE request will return a 204 response code with an empty body.

Rate Limiting

Currently, CarrierX applies no rate limiting to the partners requests to CarrierX API.

Responses

All responses return conventional HTTP status codes. Most of the responses (GET, POST, PATCH/PUT) also return objects in the JSON format.

CarrierX API allows cross-origin (CORS) requests and data transfers.

HTTP Status Codes

Typical 200 status code in the response

HTTP/2 200
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials,Content-Disposition,Access-Control-Allow-Headers
Content-Length: 1333
Content-Type: application/json
Date: Wed, 22 Sep 2021 08:23:06 GMT
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubDomains
Vary: accept-encoding

The Core API uses the following HTTP status codes:

Sample 400 status code when the JSON sent in the request body has errors in its syntax:

{
    "body": {
        "message": "cannot parse json. Check json for validity",
        "errors": null
    },
    "status": 400
}

Sample 401 status code when trying to send a request without authentication:

{
  "message": "authentication required",
  "errors": [
    {
      "field": "cause",
      "message": "authentication required",
      "reference_sid": null
    }
  ]
}

Sample 403 status code when trying to access resources you do not have enough permission for:

{
    "message": "permission denied",
    "errors": [
        {
            "field": "cause",
            "message": "permission denied",
            "reference_sid": null
        }
    ]
}

Sample 404 status code when trying to access a non-existent object (e.g., a token with an incorrect SID):

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}
Error Code Message Description
2xx Success  
200 OK The request has succeeded. The result will be a returned JSON object or a link to download a file.
201 Created The request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files.
204 No Content The server has successfully fulfilled the request. There is no additional content to send in the response payload body. This response code is normally returned to the DELETE requests.
4xx Client Errors  
400 Bad Request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
400 No JSON object could be decoded Generally an indicator that there is a syntax error.
401 Bad credentials The request requires correct user authentication.
401 Unauthorized The request requires user authentication.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404 Cannot find item by SID The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire.
404 Not Found The requested resource was not found on the server.
409 Cannot find redirect_did The redirect_did could not be found. Verify that there are available DIDs that can be assigned as redirect_did automatically or assign it manually using the Mediator API Create Binding method.
415 Unsupported media type Ensure that the header includes support for the JSON content type.
5xx Server Errors  
500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

The above status codes are common for all requests.

There are some error codes specific for certain requests only. They are described in the topics dedicated to these requests (e.g., error 422: Container Object Specific Errors).

Response Objects

Typical formatted JSON object in the response

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Successful requests return objects in the JSON format with application/json set as Content-Type. The object keys and values depend on the request and the object returned, and are described in the corresponding object sections.

Normally, the system returns the object fields unordered and unformatted. To view the object fields ordered alphabetically and “pretty-formatted” in the response to the command-line requests (e.g., cURL), use the jq command-line JSON processor or similar tools.

With jq, the request will look like this:

curl -X GET 'https://api.carrierx.com/core/v2/oauth/whoami' -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda' | jq -S

Pagination

This request returns Country objects sorting them descending by the common_name attritute, starting with the second record available, and returns a maximum of two records.

curl -X GET \
'https://api.carrierx.com/core/v2/countries?offset=2&limit=2&order=common_name+desc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous or the next key.

{
  "count": 2,
  "has_more": true,
  "items": [
    {
      "capital": "Sana'a",
      "common_name": "Yemen",
      "dialing_prefix": "967",
      "domain": "ye",
      "iso_3166_alpha_2": "YE",
      "iso_3166_alpha_3": "YEM",
      "iso_3166_numeric": 887,
      "mcc": "421",
      "official_name": "Republic of Yemen",
      "region": "Asia",
      "subregion": "Western Asia"
    },
    {
      "capital": "El Aaiún",
      "common_name": "Western Sahara",
      "dialing_prefix": null,
      "domain": "eh",
      "iso_3166_alpha_2": "EH",
      "iso_3166_alpha_3": "ESH",
      "iso_3166_numeric": 732,
      "mcc": null,
      "official_name": "Sahrawi Arab Democratic Republic",
      "region": "Africa",
      "subregion": "Northern Africa"
    }
  ],
  "limit": 2,
  "offset": 2,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=4",
    "previous": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=0"
  },
  "total": 251
}

You can use the pagination to limit the number of the objects returned in the response and sort them by the object attributes.

The pagination is available for the GET requests which return the lists of the objects without targeting them by secure IDs.

The pagination parameters include:

limit

An integer parameter that determines how many items are returned in the response. The entered value cannot exceed 1000.

The default value is 10, meaning that a maximum of ten items will be returned.

order

A string parameter that allows to sort the returned objects. Two values are accepted for this parameter:

offset

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

after/ before

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous key.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

Parameter Data Type Description
after string The secure ID of the object. The response will include only the results which follow the specified secure ID in the list of the object secure IDs.
before string The secure ID of the object. The response will include only the results which precede the specified secure ID in the list of object secure IDs.

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

Object Method Sorting (‘order’) Values
Call Detail Record Get Call Detail Records method date_stop
SMS Detail Record Get Message Detail Records method date_insert

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response

The JSON response for a successful query using the pagination parameters will include the following attributes:

Attribute Data Type Description
count integer The number of items present in the response.
has_more boolean Whether or not there are more records existing outside of the queried parameters (e.g., if the number of items that exist exceeds the limit value, the has_more value in the response will be set to true).
items array of objects The list of the objects which match the request with the pagination query parameters applied.
limit integer The limit value applied to the request.
offset integer The offset value applied to the request.
pagination object The links that allow getting the objects which precede or follow the objects in the response due to the offset or after/ before arguments used in the request. This attribute will be an empty object if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include the next or previous URLs, or both of them.
total integer The total number of the queried objects that match the search criteria. This value will be set to null with the uncountable objects (call detail records, messages, etc.)

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing results to the conference endpoint type

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=type+eq+conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The following response includes all of the endpoints that fit the filter criteria

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "properties": {
                "account_sid": "bdrU77AFb-Y1sDwqqxkeb.M3LP7hSKYg",
                "api_url": "https://api.carrierx.com/conference/v1",
                "container_sid": "null",
                "login": "username",
                "password": "password"
            },
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

The filter parameter is used to restrict or customize the JSON response. Operators can be combined for more specific searches, and are added to the query URL.

Result Filtering Quick Reference

Operator Definition Example Description
eq Equal to: this search looks for the exact value entered. name eq my_mediator The search results will include the records that have the exact my_mediator value for the name field.
ge Greater than or equal to: this search returns records where the value is greater than or equal to the field listed. wait_origination_did_ttl ge 70000 The search results will include the records that have the wait_origination_did_ttl field value greater than or equal to 70000.
gt Greater than: this search returns records where the value is exceeded for the field listed. maximum_ttl gt 40000 The search results will include the records that have the maximum_ttl field value greater than 40000.
ilike This search returns records containing the value indicated in the string passed. This form of search is case insensitive. name ilike AccOUnt% The search results will include the records that have the name field value starting with Account.
in In: this search returns records where the current value of the specified field must be in the specified list. status in (active, suspended) The search results will include the records that have the status field value equal to either active or suspended.
le Less than or equal to: this search returns records where the value is less than or equal to the field listed. wait_origination_did_ttl le 90000 The search results will include the records that have the wait_origination_did_ttl field value less than or equal to 90000.
like The same functionality as ilike but case sensitive. name like Account% The search results will include the records that have the name field value starting with Account.
lt Less than: this search returns records where the value is less than the field listed. maximum_ttl lt 10000 The search results will include the records that have the maximum_ttl field value less than 10000.
ne Not equal to: this search returns records that do not include the current values for the specified field. name ne my_mediator The search results will include the records that do not have the my_mediator value for the name field.
notin Not in: this search returns records where the current value of the specified field must not be in the specified list. status notin (active) The search results will include the records that do not have a status field value of active.

Field Filtering

In the following, we request Endpoint objects without the properties field.

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

The following response excludes the properties field from returned Endpoint objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "out_sip_password": null,
            "out_sip_username": null,
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

There are two parameters associated with field filtering: include_fields, and exclude_fields. By default, the fields included in JSON responses are specific to the request made. These returned fields are explained in the Object section for that object.

Refer to the specific object to determine which fields can be included and excluded from the JSON responses.

include_fields and exclude_fields accept comma-separated strings as values.

Field Filtering Quick Reference

Parameter Data Type Description
exclude_fields string The comma-separated list of fields to be excluded from the response. The fields depend on the object. See the Object section for that object to see which fields return.
include_fields string The comma-separated list of fields to be included in the response. The fields depend on the object. See the Object section for that object to see which fields return.

Core Concepts

This section outlines core concepts having to do with the Core API.

Batch Operations

The Batch API allows you to create, update, and delete tasks. Tasks are bulk operations that modify one or more phonenumber or prefix. When you create a batch task, you will have the option to review the items if you set the review field to boolean true value. In this case, your returned JSON status will be pending_review.

If the changes look correct, you can make a PATCH or PUT request to change the status from pending_review to approved. If the items look incorrect, the batch request can be prevented from proceeding by changing the status to cancelled.

Callbacks

The CarrierX API enables callbacks to be sent to a URL. This callback is triggered when a specific action occurs, such as when either sending or receiving an SMS. The callback data will be the object that was affected. For example, if an SMS was sent to or from a phone number associated with a callback URL, the callback will be the SMS object.

Callbacks are assigned on either the DID object or the Partner object. If a callback URL is assigned on both the DID object level and the Partner object level, the DID object callback URL will override the Partner object callback URL.

On the Partner object, callbacks for SMS activity are set for the field sms in the callbacks object. And callbacks for mediator endpoints activity are set for the field app_mediator. On the DID object, callbacks related to SMS activity are set as the value of the callback_url field.

sms and callback_url Callback

The callback response. Refer to the SMS object for more information about each attribute and value.

{
    "date_created": "2016-04-21T17:42:55.000Z",
    "date_status_changed": "2016-04-21T17:42:55.000Z",
    "direction": "inbound",
    "from_did": "15162065319",
    "mcc": null,
    "message": "This is a test inbound message delivered by CarrierX",
    "message_segments": 1,
    "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
    "mnc": null,
    "partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
    "price": "1",
    "status": "received",
    "to_did": "15162065318"
}

This callback is triggered when an action related to an SMS event occurs. Refer to the SMS object for a list of all attributes in the object.

sms and callback_url callbacks are currently only sent when SMS activity occurs.

app_mediator Callback

The app_mediator callback response

{
    "attributes":{},
    "date_insert":"2019-01-25T18:12:10.770Z",
    "date_start":"2019-01-25T18:08:23.000Z",
    "date_stop":"2019-01-25T18:09:08.000Z",
    "date_talk":"2019-01-25T18:08:44.000Z",
    "direction":"inbound",
    "dr_sid":"2a217f8d-df41-4e3d-bece-c72eaa2a8e2a",
    "dtmf":null,
    "duration":45,
    "endpoint_sid":"632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
    "endpoint_type":"mediator",
    "event_type":"binding",
    "number_dst":"15162065344",
    "number_redirect":"15162065346",
    "number_src":"15162065345",
    "partner_sid":"ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "reference_sid":"05561bef-ce48-4823-a847-bf10f7837a42",
    "type":"mediator",
    "version":2
}

This callback is triggered when a call is made to a mediator binding.

Attribute Data Type Description
attributes object The mediator attributes.
date_insert string The date and time when the Call Detail Record was processed and added to the database.
date_start string The date and time when the call started.
date_stop string The date and time when the call stopped.
date_talk string The date and time when the call is answered.
direction string The direction of the call, either inbound or outbound.
dr_sid string The secure ID of the record.
dtmf string The DTMF sequence of the binding.
duration string The duration of the call.
endpoint_sid string The endpoint secure ID.
endpoint_type string The type of endpoint that triggered the callback.
event_type string The event type.
number_dst string The destination phone number.
number_redirect string The redirect phone number.
number_src string The source phone number.
partner_sid string The partner secure ID.
reference_sid string The binding_sid that was matched for the call.
type string The endpoint type.
version string The API version.

Call Routing

CarrierX call routing connects IP communications infrastructure with the PSTN. Call routing works slightly differently depending on the direction of the communication, either inbound or outbound.

Hosted Endpoints: Conference, FlexML, and Mediator
Inbound communications come in from the PSTN and hit the CarrierX switches, which have configured trunks. Trunks are organized and managed in trunk groups. These entities hold settings that determine how the communication is processed. Outbound communications start from an IP-based application and move through a configurable SIP trunk, and are sent to the PSTN.

Call Routing

Third-Party Endpoints
Similar to hosted endpoints, inbound communications from the PSTN reach the CarrierX switches. The communications go through a configured trunk and then your external application. Outbound communications still come from your rented DIDs, but they go through your third-party configured endpoint, which integrates with an external IP. This communication still moves to the trunk and out to the PSTN.

Third-Party Routing

The main difference is that the hosted endpoints (Conference, FlexML, and Mediator) are hosted by CarrierX. The third-party endpoint is hosted externally, not by CarrierX.

Transformations

Transformations look like the following

{
    "action":"set_header_parameter",
    "direction":"any",
    "operands":["P-Charging-Vector","orig-ioi","privateSIP"]
}

Note that you can use regular expressions in transformations. For example, the following will check if the phone number has a 1 prefix and add one if not.

{
    "transformations": [
        {
            "action": "rewrite_to",
            "direction": "any",
            "operands": ["^([2-9]\\d{9})$", "1\\1"]
        },
        {
            "action": "rewrite_from",
            "direction": "any",
            "operands": ["^([2-9]\\d{9})$", "1\\1"]
        }
    ]
}

Transformations are applied to endpoints, partners, DIDs, prefixes, trunk groups, and trunks. They modify values when an object is updated. Transformations have three parts: action, direction, and operands.

Attribute Data Type Description
action string The action to be executed for the transformation. Refer to the sections below for a list of all actions.
direction string The direction of communication that the transformation applies to. Values accepted in this field are:
  • any—the selected transformation is applied when the entity is sending or receiving calls.
  • inbound—the selected transformation is applied when the entity is receiving calls.
  • outbound—the selected transformation is applied when the entity is sending calls.
  • undirected—the selected transformation is applied unrelated to the direction.
operands array The values to be transformed. Operands can include set values or regular expressions.

if_match

Sample if_match transformation

{
    "action": "if_match",
    "direction": "inbound",
    "operands": [
        "{{stir_verstat}}",
        "TN-Validation-Failed",
        "reject",
        "forbidden"
    ]
}

The if_match action is used to add conditions based on which other transformations are applied.

The action accepts from three to 100 operands: if_match(value, match, action, arg1, argX)

Operand Data Type Description
value string The string value with interpolated fields.
match string The regular expression to match.
action string The action to take if the regular expression succeeds. This action is another transformation.
arg1 string The first argument of the transformation action.
argX string The next arguments of the transformation action.

lookup_rn

Sample lookup_rn transformation

{
    "action": "lookup_rn",
    "direction": "inbound",
    "operands": [
        "true",
        "true",
        "{{src}}",
        "from",
        "ignore",
        "e164",
        "domestic",
        "e164_with_plus",
        "passthrough"
    ]
}

The lookup_rn action is used to lookup the routing number and return it so that it could be used instead of the source or destination number.

The action accepts nine operands: lookup_rn(force, always, phonenumber, destination, on_failure, input_format, output_format_domestic, output_format_international, output_format_guess_not_found)

Operand Data Type Description
force boolean Force lookup mode.
  • If true, always lookup the routing number, even if the npdi field is already set in the SIP URI.
  • If false, the number from the rn attribute will be used instead.
The default value is false.
always boolean Always include the routing number.
  • If true, always add the routing number to the destination field.
  • If false, this will only be included if a routing number was found.
The default value is false.
phonenumber string The phone number to look up. Usually {{dst}} (destination) to look up the routing number for the called party or {{src}} (source) for the calling party. The default value is {{dst}}.
destination string The destination field where the routing number will be stored.
  • If to or from, the routing number will be stored using the npdi and rn attributes.
  • If set to some other value, the routing number will be stored in a custom header of this name.
The default value is to.
on_failure string The behavior on the transformation request failure. Values accepted in this field are:
  • die to reject the call with the 503 status code.
  • ignore to continue with the call passing the original npdi value if it is present, but the system performed the lookup due to force operand set to true. If the npdi value is missing, continue with the call but do not add npdi=true or rn headers to it.
  • original_npdi_or_die to pass the original npdi value if it is present, but the system performed the lookup due to force operand set to true. Or reject the call with the 503 status code if the value is missing.
The default value is die.
input_format string The destination number input format. The transformation will try to determine if number is domestic or international, and only perform lookup if it looks like domestic. Values accepted in this field are:
  • e164 for the number to be considered domestic and perform lookup if the number is 11 digits long and starts with 1. Otherwise, the phone number is considered international and lookup is not performed.
  • guess for the number to be considered domestic and perform lookup if the number starts with +1 and is 11 digits long. If the number does not start with +, but starts with 1 and is 11 digits long, then it is considered domestic and lookup is performed. If the number does not start with + and is 10 digits long, then the number type is set to guess and lookup is performed. Otherwise, the phone number is considered international and lookup is not performed.
  • ignore_plus is used if the source may add extraneous + that should not be trusted. If the number is 11 digits long, and starts with 1, then the number is considered domestic and lookup is performed. If the number is 10 digits long, then the number type is set to guess and lookup is performed. Otherwise, the phone number is considered international and lookup is not performed.
The default value is guess.
output_format_domestic string The output format for the numbers considered domestic or with the type set to guess by the input_format operand and LRN found. Values accepted in this field are:
  • domestic to output the number in a 10-digit format.
  • e164 to output the number in the E.164 11-digit format.
  • e164_with_plus to output the number in the E.164 11-digit format with +.
The default value is domestic.
output_format_international string The output format for the numbers considered international by the input_format. Values accepted in this field are:
  • e164 to output the number in the E.164 11-digit format without +.
  • e164_with_plus to output the number in the E.164 11-digit format with +.
  • passthrough to use the original number exactly as it was passed.
The default value is passthrough.
output_format_guess_not_found string The output format if the destination number type is set to guess by the input_format operand and no lookup routing number was found. Values accepted in this field are:
  • domestic to output the number in a 10-digit format.
  • e164 to output the number in the E.164 11-digit format without +.
  • e164_with_plus to output the number in the E.164 11-digit format with +.
  • passthrough to use the original number exactly as it was passed.
The default value is passthrough, non-default values will be applied only if the always operand is set to true.

reject

Sample reject transformation

{
    "action": "reject",
    "direction": "inbound",
    "operands": [
        "busy"
    ]
}

The reject action is used to reject the call with one of the supported reasons.

The action accepts from one to two operands: reject(reason, message)

Operand Data Type Description
reason string The reject reason. Refer to the table below for a complete list of the reasons available.
message string The additional message about the reject reason. This is an optional field.

Reject Reasons

An example of the reject transformation with intermediary-rejected as a reject reason. My reason for rejecting the call will be returned as the additional message to the caller as a part of the Call-Info SIP header:

{
    "action": "reject",
    "direction": "inbound",
    "operands": [
        "intermediary-rejected",
        "My reason for rejecting the call"
    ]
}

Sample Call-Info SIP header returned from the above reject transformation with the intermediary-rejected reject reason

Call-Info: "My reason for rejecting the call"
Response Code Reject Reason Description
forbidden/rejected 403 Forbidden The destination understood the request, but is refusing to fulfill it.
not-found 404 Not Found The destination could not be found.
busy-here 486 Busy Here The destination is busy at the current location.
bad-gateway 502 Bad Gateway Network is out of order and the call cannot be accepted.
unavailable 503 Service Unavailable Temporary failure.
busy 600 Busy Everywhere All possible destinations are busy.
decline 603 Decline The destination does not wish to participate in the call or cannot do so.
does-not-exist 604 Does Not Exist Anywhere The server has authoritative information that the requested destination does not exist anywhere.
unwanted 607 Unwanted The destination does not want to accept the call from the current calling party. All future attempts from the same source are likely to be similarly rejected.
intermediary-rejected 608 Rejected The intermediary machine or process rejected the call attempt from the calling party. This status code usually informs the calling party that the decision has been made by an analytics engine or some other similar engine.

rewrite_from

Sample rewrite_from transformation

{
    "action": "rewrite_from",
    "direction": "any",
    "operands": [
        "^([2-9]\\d{9})$",
        "1\\1"
    ]
}

The rewrite_from action is used to rewrite the phone number of the incoming call.

The action accepts two operands: rewrite_from(pattern, replace)

Operand Data Type Description
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.

rewrite_from_header_param

Sample rewrite_from_header_param transformation

{
    "action": "rewrite_from_header_param",
    "direction": "any",
    "operands": [
        "cnam",
        "(.{1,14})",
        "\\1*"
    ]
}

The rewrite_from_header_param action is used to replace the parameters of the From header.

The action accepts three operands: rewrite_from_header_param(parameter, pattern, replace)

Operand Data Type Description
parameter string The parameter of the From header to change. The parameters, which can be safely changed without dropping the call, are: caller-rn, cnam, and isup-oli.
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.

rewrite_header

Sample rewrite_header transformation

{
    "action": "rewrite_header",
    "direction": "any",
    "operands": [
        "X-Custom-Header",
        ":5060",
        ":6060",
        "sip:10.1.5.200:5060"
    ]
}

The rewrite_header action is used to replace the header (or a part of it) you specify as an operand with the new values, or create it, in the case the call data lacks it.

The action accepts four operands: rewrite_header(header, pattern, replace, default)

Operand Data Type Description
header string The header to change.
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.
default string If the header is missing from the call, it will be created and set to the default value.

rewrite_header_parameter

Sample rewrite_header_parameter transformation

{
    "action": "rewrite_header_parameter",
    "direction": "any",
    "operands": [
        "Remote-Party-ID",
        "privacy",
        "full",
        "cnam",
        "id"
    ]
}

The rewrite_header_parameter action is used to replace the parameter of the header you specify as an operand with the new value, or create it, in the case the call data lacks it.

The action accepts five operands: rewrite_header_parameter(header, parameter, pattern, replace, default)

Operand Data Type Description
header string The header in which the parameter will be changed.
parameter string The header parameter to change.
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.
default string If the parameter is missing from the call, it will be created and set to the default value.

rewrite_to

Sample rewrite_to transformation

{
    "action": "rewrite_to",
    "direction": "any",
    "operands": [
        "^([2-9]\\d{9})$",
        "1\\1"
    ]
}

The rewrite_to action is used to rewrite the destination phone number.

The action accepts two operands: rewrite_to(pattern, replace)

Operand Data Type Description
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.

rewrite_to_header_param

Sample rewrite_to_header_param transformation

{
    "action": "rewrite_to_header_param",
    "direction": "any",
    "operands": [
        "npdi",
        "yes",
        "no"
    ]
}

The rewrite_to_header_param action is used to replace the parameters of the To header.

The action accepts three operands: rewrite_to_header_param(parameter, pattern, replace)

Operand Data Type Description
parameter string The parameter of the To header to change.
pattern string The value to be replaced. Also accepts regular expressions.
replace string The new value with which the pattern will be replaced.

set_header

Sample set_header transformation

{
    "action": "set_header",
    "direction": "any",
    "operands": [
        "X-Custom-Header",
        "sip:10.1.5.200:5060"
    ]
}

The set_header action is used to add a new header.

The action accepts two operands: set_header(header, value)

Operand Data Type Description
header string The header to be added.
value string The value for the header.

set_header_parameter

Sample set_header_parameter transformation

{
    "action": "set_header_parameter",
    "direction": "any",
    "operands": [
        "P-Charging-Vector",
        "orig-ioi",
        "privateSIP"
    ]
}

The set_header_parameter action is used to set a parameter to an existing header.

The action accepts three operands: set_header_parameter(header, parameter, value)

Operand Data Type Description
header string The header which is going to be modified.
parameter string The header parameter to be set.
value string The value for the header parameter. If the value is "" and the header parameter exists, it will be deleted.

set_user_data

Sample set_user_data transformation

{
    "action": "set_user_data",
    "direction": "any",
    "operands": [
        "identity",
        "{{SipHeader_Identity}}"
    ]
}

The set_user_data action is used to add custom user data to the call detail records. The transformation saves the data as a JSON object to the user_data attribute of the Call Detail Record object.

The action accepts two operands: set_user_data(key, value)

Operand Data Type Description
key string A user-defined custom key that will be displayed as a part of the user_data attribute of the call detail record.
value string A user-defined custom value of the key that will be displayed as a part of the user_data attribute of the call detail record.

stir_validate

Sample stir_validate transformation

{
    "action": "stir_validate",
    "direction": "any",
    "operands": []
}

The stir_validate action is used to validate the call and returns data that can be used with other transformations.

The action does not accept any operands, but instead enables the use of the following variables:

API Reference

The Core API has the following sections: Access Control, Batch, Calls, Countries, Endpoints, Invoices, Lookup, OAuth, Partners, Phone Numbers, Push, Rating, Shortener, SMS, Storage, Trunk Groups, and Verification.

Access Control

Access Control consists of two concepts—Access Control Rules and Access Control Lists. Access Control Rules (ACRs) are criteria that can be applied to calls and SMS to form the building blocks of CarrierX access control policies. Access Control Lists (ACLs) combine ACRs and policy statements to determine if an action will be allowed or rejected.

Access Control List Object

This section describes the elements of the Access Control List object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Access Control List object

{
    "access_control_rules": [
        "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
        "6fd782fa-c80b-4299-9b91-78797eb392e1"
    ],
    "direction": "outbound",
    "sms_action_false": null,
    "sms_action_true": null,
    "voice_action_false": null,
    "voice_action_true": "reject503"
}
Attribute Data Type Description
access_control_rules read only array The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction read only string The direction for the access control list. Values accepted in this field are:
  • any to apply the rules from the list to both sent and received calls and messages.
  • inbound to apply the rules from the list to received calls and messages.
  • outbound to apply the rules from the list to sent calls and messages.
  • undirected to apply the rules from the list to actions with no direction specified.
sms_action_false read only string The action to be executed for SMS messages if no access control rules are applied. Values accepted in this field are accept and reject.
sms_action_true read only string The action to be executed for SMS messages if any access control rules are applied. Values accepted in this field are accept and reject.
voice_action_false read only string The action to be executed for calls if no access control rules are applied. Values accepted in this field are:
  • accept to accept the calls.
  • reject403 to reject the call with the 403 status code.
  • reject503 to reject the call with the 503 status code.
voice_action_true read only string The action to be executed for calls if any access control rules are applied. Values accepted in this field are:
  • accept to accept the calls.
  • reject403 to reject the call with the 403 status code.
  • reject503 to reject the call with the 503 status code.

Look Up Effective ACLs for Calls

GET /accesscontrol/effective_acl/calls
Returns effective ACLs for calls

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/calls' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Access Control List objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "effective_acls": [
                {
                    "access_control_rules": [
                        "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
                        "6fd782fa-c80b-4299-9b91-78797eb392e1"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": null,
                    "voice_action_false": null,
                    "voice_action_true": "reject503"
                }
            ],
            "layer": 1
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of effective Access Control Lists (ACLs) for calls for the partner or trunk group, targeted by secure ID.

GET /accesscontrol/effective_acl/calls

This request is enabled for Field Filtering. Additionally, query arguments are used to narrow the results.

Required Scopes

To get information about Access Control Lists the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
direction string The direction for the Access Control List. Values accepted in this field are:
  • any
  • inbound
  • outbound
  • undirected
partner_sid string The partner secure ID.
trunk_group_sid string The trunk group secure ID.

Look Up Effective ACLs for SMS

GET /accesscontrol/effective_acl/sms
Returns effective ACLS for SMS

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/sms' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Access Control List objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "effective_acls": [
                {
                    "access_control_rules": [
                        "93525bae-f9a9-446b-b92a-7f421df7a11e"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": "accept",
                    "voice_action_false": null,
                    "voice_action_true": null
                }
            ],
            "layer": 1
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns the list of effective Access Control Lists (ACLs) for SMS for the partner, targeted by secure ID.

GET /accesscontrol/effective_acl/sms

This request is enabled for Field Filtering. Additionally, query arguments are used to narrow the results.

Required Scopes

To get information about Access Control Rules the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
direction string The direction for the Access Control List. Values accepted in this field are:
  • any
  • inbound
  • outbound
  • undirected
partner_sid string The partner secure ID.

Access Control Rule Object

This section describes the elements of the Access Control Rule object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Access Control Rule object

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}
Attribute Data Type Description
entries create update array The list of entries to compare against the field value.
field create update string The field from the call or SMS to check. This value will be used in comparison with entries.
name create update string The access control rule name. The value will be set to N/A if not specified otherwise.
operation create update string Determines how the value is checked. Values accepted in this field are:
  • exact for the exact match of the entries with the field value.
  • prefix for the entries to match only the beginning of the field value.
  • regexp for the entries which are the regular expressions instead of the exact values.
quantifier create update string The type of comparison to be made between entries and field. Values accepted in this field are:
  • all to determine that all the entries must be matched for the rule to work.
  • any to determine that at least one of the entries must be matched for the rule to work.
  • none to determine that none of the entries must match for the rule to work.
read_only read only boolean Shows whether the access control rule can be modified or not. Values accepted in this field are:
  • false to allow the rule modifications.
  • true to protect the rule from being edited.
The default value is false for the rules created by the partner, true for the rules created by the parent partner.
rule_sid read only string The access control rule secure ID.

Create Access Control Rule

/accesscontrol/rules
Creates an access control rule

curl -X POST \
'https://api.carrierx.com/core/v2/accesscontrol/rules' \
-H 'Content-Type: application/json' \
--data-binary '{"field":"to", "quantifier":"any", "entries": ["1800","1615"], "operation":"prefix"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Access Control Rule object

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

This request adds a new Access Control Rule (ACR) for the currently logged in partner.

/accesscontrol/rules

Required Scopes

To create an Access Control Rule object, the partner must have one of the following scopes enabled:

Body Arguments

JSON representation of the fields and values of the Access Control Rule object to be created.

Required fields to create an access control rule are:

The field parameter should contain the value against which messages or calls will be checked.

Refer to this table to view all fields that appear in the Access Control Rule object.

Get Access Control Rules

GET /accesscontrol/rules
Returns access control rules matching the criteria in the request URL

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

Response 200 status code with a list of Access Control Rule objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "entries": [
                "18007"
            ],
            "field": "called",
            "name": "1st",
            "operation": "prefix",
            "quantifier": "any",
            "read_only": true,
            "rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/accesscontrol/rules?limit=1&offset=1"
    },
    "total": 56
}

This request returns a list of Access Control Rules (ACRs) that match the given criteria, and that belong to the currently logged-in partner and parent partner.

GET /accesscontrol/rules

A partner will not be able to view ACRs created by sub-partners. The read_only field shows whether or not the ACRs belong to the currently logged-in partner.

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

Required Scopes

To get information about Access Control Rule objects, the partner must have one of the following scopes enabled:

Get Access Control Rule by SID

GET /accesscontrol/rules/{rule_sid}
Returns an access control rule, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules/dafd993d-0e99-4af9-b8fc-436fb01b0bbe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Access Control Rule object

{
    "entries": [
        "18007"
    ],
    "field": "called",
    "name": "1st",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": true,
    "rule_sid": "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
}

This request returns data for a particular access control rule (ACR), targeted by secure ID.

GET /accesscontrol/rules/{rule_sid}

Returned ACRs apply to the partner and the parent partner.

This request is enabled for Field Filtering.

Required Scopes

To get information about an Access Control Rule object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
rule_sid required string The Access Control Rule secure ID.

Update Access Control Rule

PATCH /accesscontrol/rules/{rule_sid}
Updates the Access Control Rule object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Content-Type: application/json' \
--data-binary '{"operation":"exact"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated Access Control Rule object

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "exact",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}

This request updates an access control rule, targeted by secure ID.

PATCH /accesscontrol/rules/{rule_sid}
PUT /accesscontrol/rules/{rule_sid}

An Access Control Rule object can be updated using either a PATCH or PUT request.

Required Scopes

To update an Access Control Rule object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
rule_sid required string The access control rule secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

Refer to this table to view all fields that appear in the Access Control Rule object.

Delete Access Control Rule

DELETE /accesscontrol/rules/{rule_sid}
Deletes an Access Control Rule, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes an Access Control Rule object, targeted by secure ID.

DELETE /accesscontrol/rules/{rule_sid}

ACRs can only be deleted when associated with the partner. Partners cannot delete an ACR for a parent partner when the value of read_only is true.

Required Scopes

To delete an Access Control Rule object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
rule_sid required string The secure ID of the Access Control Rule to delete.

Batch

Batch tasks create, edit, or delete phonenumber and prefix objects.

Task Object

This section describes the elements of the batch task object.

Sample Task object

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2019-10-30T20:47:32.517Z",
    "date_modified": "2019-10-30T20:47:32.517Z",
    "entries": [
        "18053355112",
        "18053355280"
    ],
    "error_details": [],
    "failure": null,
    "field": "phonenumber",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": null,
    "review": true,
    "status": "created",
    "success": null,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": null,
    "type": "phonenumber"
}
Attribute Data Type Description
data create array of objects The payload for this request. This field should be empty for DELETE.
date_created read only string The date and time when the task was created.
date_modified read only string The date and time when the task was modified.
entries create array This is based on field. Determines the existing entry. This value should be empty for POST.
error_details read only array of objects The error operation details, referenced with entry for PATCH and DELETE requests. Refer to the table below for more information.
failure read only integer The count of unsuccessful operations.
field create string The field used to determine the existing entry. This value only applies to the PATCH and DELETE methods. The value should be empty for POST.
method create string The method used for the request, either POST, PATCH, or DELETE.
partner_sid read only string The secure ID of the partner associated with the task.
processed read only integer The count of processed operations.
review create boolean Whether the task needs reviewing.
status update string The status for the current task. Refer to the table below for a comprehensive list of statuses.
success read only integer The count of successful operations.
task_sid read only string The task secure ID.
total read only integer The total count of operations.
type create string The type of task, either phonenumber or prefix.

Error Detail Object

Attribute Data Type Description
error read only object The error detail error object.
key read only object The error detail key object.

status

Value Description
approved The task has been approved and will execute.
cancelled The task has been cancelled and will not execute.
completed The task is completed.
created The batch of objects has been created.
pending_review The task is pending review and has not been executed.
queued The task is in queue.
running The task is currently running.

Create Task

/batch/tasks
Creates a batch task

curl -X POST \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Content-Type: application/json' \
--data-binary '{"method": "PATCH", "type": "phonenumber", "field":"phonenumber", "entries":["18053355112", "18053355280"], "data":{"trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"}}'\
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Task object

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2019-10-30T20:47:32.517Z",
    "date_modified": "2019-10-30T20:47:32.517Z",
    "entries": [
        "18053355112",
        "18053355280"
    ],
    "error_details": [],
    "failure": null,
    "field": "phonenumber",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": null,
    "review": true,
    "status": "created",
    "success": null,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": null,
    "type": "phonenumber"
}

This request creates a batch task.

/batch/tasks
/admin/batch/tasks

Required Scopes

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

Body Arguments

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

Required fields to create a batch task depend on the method field value of the Task object:

“method” Field Value Required Fields
"DELETE" entries, field, method, type
"PATCH" data, entries, field, method, type
"POST" data, method, type

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

Get Tasks

GET /batch/tasks
Returns tasks matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Task objects associated with the credentials

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "data": {
                "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
            },
            "date_created": "2019-10-30T20:47:32.000Z",
            "date_modified": "2019-10-30T20:47:38.000Z",
            "entries": [
                "18053355112",
                "18053355280"
            ],
            "error_details": [],
            "failure": 0,
            "field": "phonenumber",
            "method": "PATCH",
            "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
            "processed": 0,
            "review": true,
            "status": "pending_review",
            "success": 0,
            "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
            "total": 1,
            "type": "phonenumber"
            }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of tasks.

GET /batch/tasks
GET /admin/batch/tasks

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

Required Scopes

To get information about a Task object, the partner must have one of the following scopes enabled:

Get Task by SID

GET /batch/tasks/{task_sid}
Returns a batch task, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Task object

{
    "data": {
      "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2019-10-30T20:47:32.000Z",
    "date_modified": "2019-10-30T20:47:38.000Z",
    "entries": [
        "18053355112",
        "18053355280"
    ],
    "error_details": [],
    "failure": 0,
    "field": "phonenumber",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": 0,
    "review": true,
    "status": "pending_review",
    "success": 0,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": 2,
    "type": "phonenumber"
}

This request returns data for a batch task, targeted by secure ID.

GET /batch/tasks/{task_sid}
GET /admin/batch/tasks/{task_sid}

Required Scopes

To get information about a Task object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
task_sid required string The secure ID of the task.

Update Task

PATCH /batch/tasks/{task_sid}
Updates the Task object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Content-Type: application/json' \
--data-binary '{"status":"approved"}'\
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated Task object

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2019-10-30T20:47:32.000Z",
    "date_modified": "2019-10-30T20:51:23.189Z",
    "entries": [
        "18053355112",
        "18053355280"
    ],
    "error_details": [],
    "failure": 0,
    "field": "phonenumber",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": 0,
    "review": true,
    "status": "approved",
    "success": 0,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": 2,
    "type": "phonenumber"
}

This request updates a task, targeted by secure ID.

PATCH /batch/tasks/{task_sid}
PATCH /admin/batch/tasks/{task_sid}
PUT /batch/tasks/{task_sid}
PUT /admin/batch/tasks/{task_sid}

A Task object can be updated using either a PATCH or PUT request.

Required Scopes

To update a Task object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
task_sid required string The task secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

The only field that can be updated is status if the current value is pending_review. The status can be changed to either approved or cancelled.

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

Delete Task

DELETE /batch/tasks/{task_sid}
Deletes a batch task, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes a Task object, targeted by task secure ID.

DELETE /batch/tasks/{task_sid}
DELETE /admin/batch/tasks/{task_sid}

Required Scopes

To delete a Task object, the partner must have one of the following scopes enabled:

Batch Review

When you create a batch task, it has an option to review the items. To enable it, the review field of the Task object must be set to true.

To see the review items and check if they are valid or need corrections, you can use the Get Task Review Items by SID method. It will return the Batch Review Response object with the list of the items, which can be reviewed.

The Download CSV of Task Review Items by SID method can also be used to download the list of the task review items in the CSV format for a more convenient visual representation.

If the changes look correct, you can make a PATCH or PUT request to change the status from pending_review to approved. If the items look incorrect, the batch request can be prevented from proceeding by changing the status to cancelled.

Batch Review Response Object

Attribute Data Type Description
method read only string The batch review method. Values accepted in this field are: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, and TRACE.
review_items read only array of objects Items to be reviewed before approving the batch task. Refer to the table below for more information.
type read only string The batch task type. Values accepted in this field are phonenumber and prefix.

Batch Review Item Object

Attribute Data Type Description
description read only string The batch review item description.
fields read only object The batch review item fields, which require reviewing.
sid read only string The batch review item secure ID.
version read only integer The batch review item version.

Get Task Review Items by SID

GET /batch/tasks/{task_sid}/review_items
Returns batch task review items, targeted by task secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6/review_items' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of any associated review items

{
    "method": "PATCH",
    "review_items": [
        {
            "description": "18053355280",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "97de0cef-4c1a-478a-bb7e-e45fdca03035",
            "version": 1
        },
        {
            "description": "18053355112",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "0493d917-e23c-41db-8067-0c986df71007",
            "version": 1
        }
    ],
    "type": "phonenumber"
}

This request returns task review items associated with the task secure ID.

GET /batch/tasks/{task_sid}/review_items
GET /admin/batch/tasks/{task_sid}/review_items

Required Scopes

To get information about task review items the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
task_sid required string The secure ID of the task.

Download CSV of Task Review Items by SID

GET /batch/tasks/{task_sid}/review_items.csv
Returns task review items for a partner in the CSV format

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2630eb9b-55c2-4e29-9217-ed133e2f22d6/review_items.csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and a CSV download

This request returns a CSV of all task review items associated with the task secure ID.

GET /batch/tasks/{task_sid}/review_items.csv
GET /admin/batch/tasks/{task_sid}/review_items.csv

This request is enabled for Field Filtering.

Required Scopes

To get a CSV of all task review items the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
task_sid required string The secure ID of the task.

Calls

Calls are communications between two or more phone numbers.

Call Detail Record Object

This section describes the elements of the Call Detail Record object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Call Detail Record object

{
    "cic": null,
    "cic_original": null,
    "cic_transformed": null,
    "date_insert": "2019-01-18T15:35:03.000Z",
    "date_start": "2019-01-18T15:32:15.589Z",
    "date_stop": "2019-01-18T15:32:19.839Z",
    "date_talk": "2019-01-18T15:32:16.535Z",
    "direction": "inbound",
    "disconnect_originator": "DST",
    "diversion_dst": "+15162065451",
    "diversion_src": "+15162065451",
    "dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
    "duration": "4.25015",
    "duration_billing": "60",
    "endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
    "endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
    "identity": null,
    "ip_dst": "10.222.2.197:5060",
    "ip_src": "162.251.180.18",
    "number_billing": "15162065451",
    "number_dst": "15162065451",
    "number_dst_original": null,
    "number_dst_transformed": null,
    "number_external": "15012678830",
    "number_src": "+15012678830",
    "number_src_original": null,
    "number_src_transformed": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "price": "0.0025",
    "rate": "0.0005",
    "sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
    "sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
    "sipcause": "200",
    "stir_attest" : "A",
    "stir_identity" : "false",
    "stir_orig_id" : "+15012678830",
    "stir_signing_entity" : "carrierX",
    "stir_verstat": null,
    "trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
    "trunk_group_sid_src": null,
    "trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
    "trunk_sid_src": null,
    "type": "telecom",
    "user_data" : {
      "identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
    },
    "version": 2
}
Attribute Data Type Description
cic read only string The current Carrier Identification Code (CIC) information.
cic_original read only string The CIC information before any transformations were applied.
cic_transformed read only string The CIC information after any transformations were applied.
date_insert read only string The date and time when the detail record was inserted into the database.
date_start read only string The date and time when the call was started.
date_stop read only string The date and time when the call ended.
date_talk read only string The date and time when the destination phone number answered the call.
direction read only string The direction of the call. Values accepted in this field are:
  • any
  • inbound
  • outbound
  • undirected
disconnect_originator read only string The originator of a call drop.
diversion_dst read only string The destination diversion header.
diversion_src read only string The source diversion header.
dr_sid read only string The secure ID of the record.
duration read only number The call duration in seconds. The value is calculated as date_stopdate_start.
duration_billing read only number The calculated call duration in seconds to set the price.
endpoint_sid_dst read only string The destination endpoint secure ID. If the destination is an external phone number, this value will be populated with the System Gateway secure ID.
endpoint_sid_src read only string The source endpoint secure ID. If the source is an external phone number, this value will be populated with the System Gateway secure ID.
identity read only string The real phone number that the call is coming from. This field is populated from either PAI or RPID.
ip_dst read only string The IP address of the destination of call.
ip_src read only string The IP address of the source of call.
number_billing read only string The subscriber phone number.
number_dst read only string The destination phone number. Values accepted in this field are the calling number if the call is outbound, or the called number if the call is inbound.
number_dst_original read only string The destination phone number before any transformations were applied. This field will populate if this value is different from number_dst.
number_dst_transformed read only string The destination phone number after any transformations were applied. This field will populate if this value is different from number_dst.
number_external read only string The non-subscriber phone number.
number_src read only string The source number. Values accepted in this field are the calling number if the call is outbound, or the called number if the call is inbound.
number_src_original read only string The source phone number before any transformations were applied. This field will populate if this value is different from number_src.
number_src_transformed read only string The source phone number after any transformations were applied. This field will populate if this value is different from number_src.
partner_sid read only string The secure ID of the partner associated with the call detail record.
price read only number The price for the detail record.
rate read only number The rate that the system uses to calculate the price of the call.
sipcallid_dst read only string The SIP call ID of the destination call.
sipcallid_src read only string The SIP call ID of the source of call.
sipcause read only string The SIP code that was used to end the call.
stir_attest read only string The attestation level returned by the stir_validate transformation if the system ran it.
stir_identity read only boolean Whether the identity was received in the outbound calls or sent in the inbound calls.
stir_orig_id read only string The ID of the call originator returned by the stir_validate transformation if the system ran it.
stir_signing_entity read only string If the call is signed, this field will display the signing authority which performed the call attestation.
stir_verstat read only string The TN validation result returned by the stir_validate transformation if the system ran it. Is set to null for the calls with the inbound direction.
trunk_group_sid_dst read only string The destination trunk group secure ID.
trunk_group_sid_src read only string The source trunk group secure ID.
trunk_sid_dst read only string The destination trunk secure ID.
trunk_sid_src read only string The source trunk secure ID.
type read only string The type of call. Values accepted in this field are:
  • conference_call
  • conference_meeting
  • mediator
  • mms
  • sms
  • telecom
user_data read only object The custom user data set by the set_user_data transformation.
version read only integer The version of the detail record as it comes from the resource.

Get Call Detail Records

GET /calls/call_drs
Returns call detail records matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs?before=e4db6148-ed3b-4eb8-83ce-17d71763a359&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Call Detail Record objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "cic": null,
            "cic_original": null,
            "cic_transformed": null,
            "date_insert": "2019-01-18T15:35:03.000Z",
            "date_start": "2019-01-18T15:32:15.589Z",
            "date_stop": "2019-01-18T15:32:19.839Z",
            "date_talk": "2019-01-18T15:32:16.535Z",
            "direction": "inbound",
            "disconnect_originator": "DST",
            "diversion_dst": "+15162065451",
            "diversion_src": "+15162065451",
            "dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
            "duration": "4.25015",
            "duration_billing": "60",
            "endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
            "endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
            "identity": null,
            "ip_dst": "10.222.2.197:5060",
            "ip_src": "162.251.180.18",
            "number_billing": "15162065451",
            "number_dst": "15162065451",
            "number_dst_original": null,
            "number_dst_transformed": null,
            "number_external": "15012678830",
            "number_src": "+15012678830",
            "number_src_original": null,
            "number_src_transformed": null,
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "price": "0.0025",
            "rate": "0.0005",
            "sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
            "sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
            "sipcause": "200",
            "stir_attest" : "A",
            "stir_identity" : "false",
            "stir_orig_id" : "+15012678830",
            "stir_signing_entity" : "carrierX",
            "stir_verstat": null,
            "trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
            "trunk_group_sid_src": null,
            "trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
            "trunk_sid_src": null,
            "type": "telecom",
            "user_data" : {
              "identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
            },
            "version": 2
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/calls/call_drs?before=c02a73b2-8401-459a-af7e-f4cc3eee7854&limit=1&offset=0"
    },
    "total": null
}

This request returns data about sent and received calls including the date and time, originating and destination phone numbers, and IP addresses of the calling numbers.

GET /calls/call_drs

This request is enabled for Pagination (including after and before parameters), Result Filtering, and Field Filtering.

Required Scopes

To get information about Call Detail Record objects, the partner must have one of the following scopes enabled:

To get information about Call Detail Record objects for the inherited partners, the partner must additionally have the calls.read_descendant scope enabled.

Get Call Detail Record by SID

GET /calls/call_drs/{dr_sid}
Returns a Call Detail Record, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs/c02a73b2-8401-459a-af7e-f4cc3eee7854' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Call Detail Record object

{
    "cic": null,
    "cic_original": null,
    "cic_transformed": null,
    "date_insert": "2019-01-18T15:35:03.000Z",
    "date_start": "2019-01-18T15:32:15.589Z",
    "date_stop": "2019-01-18T15:32:19.839Z",
    "date_talk": "2019-01-18T15:32:16.535Z",
    "direction": "inbound",
    "disconnect_originator": "DST",
    "diversion_dst": "+15162065451",
    "diversion_src": "+15162065451",
    "dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
    "duration": "4.25015",
    "duration_billing": "60",
    "endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
    "endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
    "identity": null,
    "ip_dst": "10.222.2.197:5060",
    "ip_src": "162.251.180.18",
    "number_billing": "15162065451",
    "number_dst": "15162065451",
    "number_dst_original": null,
    "number_dst_transformed": null,
    "number_external": "15012678830",
    "number_src": "+15012678830",
    "number_src_original": null,
    "number_src_transformed": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "price": "0.0025",
    "rate": "0.0005",
    "sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
    "sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
    "sipcause": "200",
    "stir_attest" : "A",
    "stir_identity" : "false",
    "stir_orig_id" : "+15012678830",
    "stir_signing_entity" : "carrierX",
    "stir_verstat": null,
    "trunk_group_sid_dst": "cf7db13f-5c63-4c62-a447-fe3008cd72ef",
    "trunk_group_sid_src": null,
    "trunk_sid_dst": "7098d9f8-c8f2-400f-a31a-61ef7755985c",
    "trunk_sid_src": null,
    "type": "telecom",
    "user_data" : {
      "identity" : "eyJ0eXAiOiJwYXNzcG9ydCIsImFsZyI6I...alg=ES256;ppt=shaken"
    },
    "version": 2
}

This request returns data for a call detail record, targeted by secure ID.

GET /calls/call_drs/{dr_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Call Detail Record object, the partner must have one of the following scopes enabled:

To get information about a Call Detail Record object for the inherited partners, the partner must additionally have the calls.read_descendant scope enabled.

Path Arguments

Parameter Data Type Description
dr_sid required string The secure ID of the Call Detail Record.

Rate Object

This section describes the elements of the Rate object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Rate object

{
    "active": "yes",
    "count": 1,
    "effective_date": "2019-08-23T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.005"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": null,
    "partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
    "rates_plan": {
        "name": "retail_voice_in_rates-2019-07-05",
        "rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
    },
    "total": 9
}
Parameter Data Type Description
active read only string Whether or not that rate is effective, as determined by effective_date.
effective_date read only string The date and time when the rate becomes effective.
items read only array of objects The rate details. Refer to the table below for more information.
partner_sid read only string The secure ID of the partner associated with the rate.
rates_plan read only object The rate plan. Refer to the table below for more information.

Rate Call Object

Parameter Data Type Description
billing_increment read only number The increment in seconds by which billing will occur. Calls are rounded up to the nearest billing_increment.
billing_minimum read only number The minimum length of the call in seconds for billing.
country_code read only string The ISO 3166-1 alpha-3 code of this rate.
country_name read only string The common country name of this rate.
prefix read only string The prefix of this call rate.
price read only number The price of this rate. The price is per billing_minimum.

Rate Plan Object

Parameter Data Type Description
name read only string The name of the rate plan.
rates_plan_sid read only string The rate plan secure ID.

Get Inbound PSTN Rates

GET /calls/rates/inbound/pstn
Returns rates for inbound PSTN calls

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/pstn' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Rate objects

{
    "active": "yes",
    "count": 1,
    "effective_date": "2019-08-23T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.005"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": null,
    "partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
    "rates_plan": {
        "name": "retail_voice_in_rates-2019-07-05",
        "rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
    },
    "total": 9
}

This request returns a list of rates for receiving calls from PSTN.

GET /calls/rates/inbound/pstn

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

Download CSV of Inbound PSTN Rates

GET /calls/rates/inbound/pstn/csv
Returns inbound PSTN rates for a partner in the CSV format

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/pstn/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and a CSV download

This request returns a CSV with the list of all rates for receiving calls from PSTN.

GET /calls/rates/inbound/pstn/csv

This request is enabled for Field Filtering.

Get Inbound VoIP Rates

GET /calls/rates/inbound/voip/{sub_type}
Returns inbound VoIP rates for calls, targeted by the subtype

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/voip/conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Rate object

{
    "active": "yes",
    "count": 1,
    "effective_date": "2018-08-29T00:00:00.000Z",
    "has_more": false,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": null,
    "partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
    "rates_plan": {
        "name": "voip_conference_in_zero_rate.txt",
        "rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
    },
    "total": 1
}

This request returns a list of rates for receiving calls from VoIP, targeted by the endpoint type.

GET /calls/rates/inbound/voip/{sub_type}

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

Path Arguments

Parameter Data Type Description
sub_type required string The rate subtype. Values accepted in this field are:
  • conference
  • conference_playback
  • flexml
  • mediator
  • third_party
  • voicemail

Download CSV of Inbound VoIP Rates

GET /calls/rates/inbound/voip/{sub_type}/csv
Returns inbound VoIP rates for a partner in the CSV format

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/voip/conference/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and a CSV download

This request returns a CSV with the list of all rates for receiving calls from VoIP, targeted by the endpoint type.

GET /calls/rates/inbound/voip/{sub_type}/csv

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
sub_type required string The rate subtype. Values accepted in this field are:
  • conference
  • conference_playback
  • flexml
  • mediator
  • third_party
  • voicemail

Get Outbound PSTN Rates

GET /calls/rates/outbound/pstn
Returns outbound PSTN rates for calls

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

Response 200 status code with a serialized copy of the Rate object

{
    "active": "yes",
    "count": 1,
    "effective_date": "2019-08-23T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "6",
            "billing_minimum": "6",
            "country_code": "USA",
            "country_name": "United States",
            "prefix": "1207991",
            "price": "0.01"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "rates_plan": {
        "name": "retail_voice_out-2019-08-16",
        "rates_plan_sid": "0428d20f-7869-4cf5-aa5c-f44f99a19515"
    },
    "total": 110170
}

This request returns a list of rates for sending calls to PSTN.

GET /calls/rates/outbound/pstn

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

Download CSV of Outbound PSTN Rates

GET /calls/rates/outbound/pstn/csv
Returns outbound PSTN rates for a partner in the CSV format

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/pstn/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and a CSV download

This request returns a CSV with the list of all rates for sending calls to PSTN.

GET /calls/rates/outbound/pstn/csv

This request is enabled for Field Filtering.

Get Outbound VoIP Rates

GET /calls/rates/outbound/voip/{sub_type}
Returns outbound VoIP rates for calls, targeted by the subtype

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/voip/conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Rate object

{
    "active": "yes",
    "count": 1,
    "effective_date": "2018-08-29T00:00:00.000Z",
    "has_more": false,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "rates_plan": {
        "name": "voip_conference_out_zero_rate.txt",
        "rates_plan_sid": "0428d20f-7869-4cf5-aa5c-f44f99a19515"
    },
    "total": 1
}

This request returns a list of rates for sending calls to VoIP, targeted by the endpoint type.

GET /calls/rates/outbound/voip/{sub_type}

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

Path Arguments

Parameter Data Type Description
sub_type required string The rate subtype. Values accepted in this field are:
  • conference
  • conference_playback
  • flexml
  • mediator
  • third_party
  • voicemail

Download CSV of Outbound VoIP Rates

GET /calls/rates/outbound/voip/{sub_type}/csv
Returns outbound VoIP rates for a partner in the CSV format

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/voip/conference/csv' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and a CSV download

This request returns a CSV with the list of all rates for sending calls to VoIP, targeted by the endpoint type.

GET /calls/rates/outbound/voip/{sub_type}/csv

This request is enabled for Field Filtering.

Path Arguments

Parameter Data Type Description
sub_type required string The rate subtype. Values accepted in this field are:
  • conference
  • conference_playback
  • flexml
  • mediator
  • third_party
  • voicemail

Countries

The Countries API holds data about countries, including universally accepted formats, mobile country codes, dialing prefixes, and more.

Country Object

This section describes the elements of the Country object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Country object

{
    "capital": "Washington D.C.",
    "common_name": "United States",
    "dialing_prefix": "1",
    "domain": "us",
    "iso_3166_alpha_2": "US",
    "iso_3166_alpha_3": "USA",
    "iso_3166_numeric": 840,
    "mcc": "310,311,312,313,316",
    "official_name": "United States of America",
    "region": "Americas",
    "subregion": "Northern America"
}
Attribute Data Type Description
capital read only string The capital of the country.
common_name read only string The common name of the country.
dialing_prefix read only string The telephone code of the country.
domain read only string The Internet domain of the country.
iso_3166_alpha_2 read only string The ISO 3166-1 alpha-2 code of the country.
iso_3166_alpha_3 read only string The ISO 3166-1 alpha-3 code of the country.
iso_3166_numeric read only integer The ISO 3166-1 numeric code of the country.
mcc read only string The mobile country code.
official_name read only string The official name of the country.
region read only string The region of the country.
subregion read only string The subregion of the country.

Get Countries

GET /countries
Returns a list of countries

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

Response 200 status code with a list of Country objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "capital": "Washington D.C.",
            "common_name": "United States",
            "dialing_prefix": "1",
            "domain": "us",
            "iso_3166_alpha_2": "US",
            "iso_3166_alpha_3": "USA",
            "iso_3166_numeric": 840,
            "mcc": "310,311,312,313,316",
            "official_name": "United States of America",
            "region": "Americas",
            "subregion": "Northern America"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/countries?limit=1&offset=1"
    },
    "total": 249
}

This request returns a list of countries.

GET /countries

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

Required Scopes

To get information about Country objects, the partner must have one of the following scopes enabled:

Get Country by ISO Code

GET /countries/{country_code}
Returns a country, targeted by ISO code

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ITA?exclude_fields=common_name' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Country object

{
    "capital": "Rome",
    "dialing_prefix": "39",
    "domain": "it",
    "iso_3166_alpha_2": "IT",
    "iso_3166_alpha_3": "ITA",
    "iso_3166_numeric": 380,
    "mcc": "222",
    "official_name": "Italian Republic",
    "region": "Europe",
    "subregion": "Southern Europe"
}

This request returns the country associated with an ISO 3166-1 alpha-3 code.

GET /countries/{country_code}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Country object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
country_code required string The ISO 3166-1 alpha-3 code of the country.

Get Country by IP Address

GET /countries/ip/{ip_address}
Returns a country, targeted by IP address

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ip/2.6.26.2' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Country object

{
    "city": "Bordeaux",
    "common_name": "France",
    "iso_3166_alpha_2": "FR",
    "region": "Nouvelle-Aquitaine",
    "state": null
}

This request returns the country associated with the IP address.

GET /countries/ip/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Country object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
ip_address required string The IPv4 address.

Endpoints

An endpoint represents a device that can receive voice calls. It may be an external SIP device, such as an Asterisk server or SIP PBX, or a hosted application that CarrierX runs.

New partners are provided a system_gateway endpoint, which cannot be modified. This endpoint is a logical representation of the CarrierX switches, and determines the IP addresses where traffic is sent and received.

In call detail records, a call coming into the PSTN would designate the system_gateway endpoint as the inbound leg. The endpoint being routed to would be listed as the outbound leg. Alternatively, for inbound calls sent to a third-party endpoint, users will need their switch to accept traffic from any of the IPs listed in the system_gateway endpoint.

Endpoint Object

This section outlines the Endpoint object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Endpoint object

{
    "addresses": [],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "358d56f9-1482-4b3d-85a9-efd29afc6ff2",
    "name": "my_conf",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {
        "account_sid": "6DcA986G-vcBel19O02iIbYUAawVidvB",
        "api_url": "https://api.carrierx.com/conference/v1",
        "container_sid": "null",
        "login": "sample_conference_775",
        "password": "YnAa9s8ixJKi"
    },
    "transformations": [],
    "type": "conference",
    "voip_token": null
}
Attribute Data Type Description
addresses create update array of objects The endpoint addresses. Refer to the table below for more information.
allow_custom_caller_id admin create update boolean Whether or not to allow custom caller ID.
attributes create update object The endpoint attributes. Refer to the table below for more information.
auth_required admin create update boolean Whether or not proxy authentication is required.
capacity create update integer The maximum number of simultaneous inbound and outbound calls.
endpoint_sid read only string The endpoint secure ID.
id admin read only integer An internal identifier of the endpoint.
insecure_address admin create update boolean Whether or not the use of insecure address is allowed.
name create update string The endpoint name.
out_sip_password create string For calls sent to this endpoint and if proxy authentication is required, this password and out_sip_username will be used if no sip_password is set for the Endpoint Address object.
out_sip_username create string For calls sent to this endpoint and if proxy authentication is required, this username and out_sip_password will be used if no sip_username is set for the Endpoint Address object.
partner read only object The Partner object associated with the endpoint. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid create string The secure ID of the partner associated with the endpoint.
properties create update object The endpoint properties. Refer to the table below for more information.
template_sid admin read only string The secure ID of the template that this endpoint it based on.
transformations create update array of objects The transformations that apply to the endpoint. Refer to the transformations section for more information.
type create string The type of endpoint. Values accepted in this field are:
  • conference for the hosted endpoint that allows conference meeting rooms.
  • conference_playback for the hosted endpoint helper for Conference to allow playback of recorded files.
  • flexml for the hosted endpoint that runs customizable call flows for numbers.
  • mediator for the hosted endpoint that runs two-stage dialing application.
  • peering_receiver for the hosted endpoint that allows inbound connections but has no application attached to it.
  • peering_sender for the hosted endpoint that allows outbound connections but has no application attached to it.
  • system_gateway for the virtual endpoint that represents the CarrierX switch to the customer. This endpoint is created automatically when a new partner is created and is not modifiable.
  • third_party for a standard SIP endpoint that is configured using IP/port pairs.
  • voicemail for the hosted Voicemail endpoint.
voip_token read only string The endpoint authentication token.

Endpoint Address Object

Attribute Data Type Description
direction create update string The direction for the address. Values accepted in this field are: inbound, outbound, and any. The default value for this field is any.
dst_port create update integer If specified, this entry is only valid for calls that reach CarrierX on this port. CarrierX listens on port 5060-5069, and any of these ports may be specified. The default port value is 5060.
ip create update string The IP address or fully qualified domain name (FQDN) associated with the endpoint.
location_sid create update string The location secure ID.
port create update integer The port. The default port value is 5060.
priority create update integer The priority of the address. Lower values have higher priority. The default value is 0.
sip_password create update string For calls sent to this endpoint and if proxy authentication is required, this password and sip_username will be used. This value overrides the out_sip_password value of the Endpoint object.
sip_username create update string For calls sent to this endpoint and if proxy authentication is required, this username and sip_password will be used. This value overrides the out_sip_username value of the Endpoint object.
srtp create update boolean Allows the endpoint to receive and send calls that require the use of secure real-time transport protocol (SRTP). Values accepted in this field are:
  • true for the endpoint to accept and send SIP INVITE requests which require the use of SRTP. You should set the transport attribute to tls for this option to work.
  • false for the endpoint to drop SIP INVITE requests that require the use of SRTP, and to send INVITE using unencrypted RTP.
The default value is false.
transport create update string The protocol for the address. Values accepted in this field are: tcp, tls, and udp. The default value for this field is udp. This field applies to the Third Party endpoint.

Attributes Object

Attribute Data Type Description Applicable Endpoints
account_sid create update string The account secure ID. Mediator
api_url create update string The URL to the Mediator swagger. This field cannot be modified. Mediator
did_group_id create update string The DID group ID. Conference, FlexML
key create update string The attribute key. Any
subscriber_sid create update string The subscriber secure ID. Conference, FlexML
value create update string The attribute value. Any

Properties Object

Attribute Data Type Description Applicable Endpoints
account_sid read only string The account secure ID. Conference, FlexML, Mediator
api_url read only string The URL of the API. Conference, FlexML, Mediator
callback_method create update string The callback method used with the Voicemail endpoint. Values accepted in this field are POST and GET. The default value is POST. Voicemail
callback_url create update string The callback URL used with the Voicemail endpoint. The default value is null. Voicemail
container_sid create update string The secure ID of the container where recordings will be stored. The default value is null. Conference, FlexML, Voicemail
conference_endpoint_sid create update string The secure ID of the Conference endpoint associated with the Conference Playback endpoint. Conference Playback
greeting create update string The name of the file used as a greeting for the Voicemail endpoint. The default value is null. Voicemail
login read only string The login for the endpoint. Conference, FlexML, Mediator
max_duration create update number The maximum length of the recording in seconds used with the Voicemail endpoint. Voicemail
password read only string The password for the endpoint. Conference, FlexML, Mediator
subscriber_sid read only string The subscriber secure ID. Conference

Create Endpoint

/endpoints
Creates an endpoint
Conference endpoint

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Endpoint object

{
    "addresses": [],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "358d56f9-1482-4b3d-85a9-efd29afc6ff2",
    "name": "my_conf",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {
        "account_sid": "6DcA986G-vcBel19O02iIbYUAawVidvB",
        "api_url": "https://api.carrierx.com/conference/v1",
        "container_sid": "null",
        "login": "sample_conference_775",
        "password": "YnAa9s8ixJKi"
    },
    "transformations": [],
    "type": "conference",
    "voip_token": null
}

Third-party endpoint

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"EP_Т_1","addresses": ["ip": "1.1.2.13", "port": "5060"], "type":"third_party"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Endpoint object

{
    "addresses": [
        {
            "direction": "any",
            "dst_port": 5060,
            "ip": "1.1.2.13",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "sip_password": null,
            "sip_username": null,
            "srtp": false,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
    "name": "my_third_party",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
}

This request creates an endpoint.

/endpoints
/admin/endpoints

For the Mediator, Conference, Conference Playback, and FlexML endpoints, only the name and capacity values can be edited after the endpoint has been created. For the Voicemail endpoint, the properties attributes can be also modified.

Required Scopes

To create an Endpoint object, the partner must have one of the following scopes enabled:

Body Arguments

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

A required field to create an endpoint is type, for the third-party endpoint the required fields are ip and type. If no value for port is specified, the value for port will be assigned as 5060.

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

Get Endpoints

GET /endpoints
Returns endpoints matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=addresses.ip+eq+"1.1.2.13"' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Endpoint objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [
                {
                    "direction": "any",
                    "dst_port": 5060,
                    "ip": "1.1.2.13",
                    "location_sid": null,
                    "port": 5060,
                    "priority": 0,
                    "sip_password": null,
                    "sip_username": null,
                    "srtp": false,
                    "transport": "udp"
                }
            ],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
            "name": "my_third_party",
            "out_sip_password": null,
            "out_sip_username": null,
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "properties": {},
            "transformations": [],
            "type": "third_party",
            "voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of endpoints.

GET /endpoints
GET /admin/endpoints

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

Required Scopes

To get information about Endpoint objects, the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the endpoint should be shown. Values accepted in this field are true and false. The default value is false.

Get Endpoint by SID

GET /endpoints/{endpoint_sid}
Returns an endpoint, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints/473d1623-c615-4b43-ab4f-01cd5491c56b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Endpoint object

{
    "addresses": [
        {
            "direction": "any",
            "dst_port": 5060,
            "ip": "1.1.2.13",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "sip_password": null,
            "sip_username": null,
            "srtp": false,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
    "name": "my_third_party",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
}

This request returns data for an endpoint, targeted by secure ID.

GET /endpoints/{endpoint_sid}
GET /admin/endpoints/{endpoint_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about an Endpoint object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
endpoint_sid required string The endpoint secure ID.

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the endpoint should be shown. Values accepted in this field are true and false. The default value is false.

Update Endpoint

PATCH /endpoints/{endpoint_sid}
Updates the Endpoint object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_third_party_ep"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated Endpoint object

{
    "addresses": [
        {
            "direction": "any",
            "dst_port": 5060,
            "ip": "1.1.2.13",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "sip_password": null,
            "sip_username": null,
            "srtp": false,
            "transport": "udp"
        }
    ],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac",
    "name": "my_third_party_ep",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {},
    "transformations": [],
    "type": "third_party",
    "voip_token": "2c95517b-a5e8-4415-b471-cdd81d5a6dcb"
}

This request updates an endpoint, targeted by secure ID.

PATCH /endpoints/{endpoint_sid}
PATCH /admin/endpoints/{endpoint_sid}
PUT /endpoints/{endpoint_sid}
PUT /admin/endpoints/{endpoint_sid}

An Endpoint object can be updated using either a PATCH or PUT request.

Required Scopes

To update an Endpoint object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
endpoint_sid required string The endpoint secure ID.

Query Arguments

Parameter Data Type Description
nested_objects string Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace.

Body Arguments

JSON representation of the fields and values to be updated.

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

Delete Endpoint

DELETE /endpoints/{endpoint_sid}
Deletes an endpoint, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes an endpoint, targeted by secure ID, from a partner account.

DELETE /endpoints/{endpoint_sid}
DELETE /admin/endpoints/{endpoint_sid}

Required Scopes

To delete an Endpoint object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
endpoint_sid required string The secure ID of the endpoint to be removed.

Invoices

An Invoice object is automatically created when a new partner is added to the system. One invoice exists for each partner, and is updated when new charges occur.

Invoice Object

This section describes the elements of the Invoice object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Invoice object

{
    "amount": "0.38",
    "amount_due": "0",
    "amount_tax": "0.32",
    "balance_forward": "-0.45",
    "balance_previous": "-351.91",
    "date_billing_period_end": "2019-01-19T23:59:59.000Z",
    "date_billing_period_start": "2018-12-20T00:00:00.000Z",
    "date_charge_expected": "2019-01-19T23:59:59.000Z",
    "date_charged": null,
    "date_created": "2018-12-19T23:30:01.000Z",
    "date_issued": null,
    "display_id": "004",
    "invoice_items": [
        {
            "amount": "0.37",
            "country_code": "USA",
            "date_billing_period_end": "2019-01-19T23:59:59.000Z",
            "date_billing_period_start": "2018-12-20T00:00:00.000Z",
            "direction": "inbound",
            "type": "toll",
            "usage": 8880
        }
    ],
    "invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
    "paid": false,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "pay_items": [],
    "status": "open",
    "tax_items": [
        {
            "amount": "0.32",
            "jurisdiction": "federal",
            "type": "fed_universal_service_fund"
        }
    ]
}
Attribute Data Type Description
amount read only number The amount on the invoice. This is not necessarily due at this time.
amount_due read only number The amount due.
amount_tax read only number The tax amount due.
balance_forward read only number The balance that will be used as balance_previous for the next invoice.
balance_previous read only number The previous balance on the invoice.
date_billing_period_end read only string The date and time when the billing period ends.
date_billing_period_start read only string The date and time when the billing period begins.
date_charge_expected read only string The date and time when the invoice will be charged.
date_charged read only string The date and time when the invoice was charged.
date_created read only string The date and time when the invoice was created.
date_issued read only string The date and time when the invoice was issued.
display_id read only string The ID on the rendered invoice.
invoice_items read only array The details about each of the invoice items. Refer to the table below for more information.
invoice_sid read only string The invoice secure ID.
paid read only boolean Shows if the invoice has been paid. Values accepted in this field are: true and false.
partner read only object The Partner object associated with the invoice. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the invoice.
pay_items read only array of objects The payments made while the invoice was open. Refer to the table below for more information.
status read only string The invoice status. Values accepted in this field are:
  • charging for an invoice that is being charged.
  • complete for an invoice that has been charged.
  • created for an invoice that has been created.
  • declined for an invoice that belongs to a partner without a billing method on file, or an invoice with a payment declined.
  • error for a billing module received an error while processing the invoice; invoice may need to be processed manually.
  • open for an open invoice.
  • pending for an invoice that belongs to a partner with a billing method of check on file; this indicates that a check is anticipated.
  • reviewing for an invoice that is awaiting manual approval.
  • uncollectable for an invoice that will not be paid.
tax_items read only array of objects The tax items details. Refer to the table below for more information.

Invoice Item Object

Attribute Data Type Description
amount read only number The invoice item price total.
country_code read only string The ISO 3166-1 alpha-3 code of the service type associated with this invoice item.
date_billing_period_end read only string The date and time when this item billing period ended.
date_billing_period_start read only string The date and time when this item billing period started.
direction read only string The direction of the call or SMS/MMS, either inbound or outbound.
type read only string The type of call, SMS/MMS, transcription, or text-to-speech used. Values accepted in this field are:
  • adjustment
  • bridge
  • did
  • did_lookup_carrier
  • did_lookup_cnam
  • did_lookup_lrn
  • mms
  • sms
  • toll
  • toll_free
  • transcription_average
  • transcription_high
  • transcription_low
  • tts
usage read only integer The number of times the item was used.

Invoice Pay Item Object

Attribute Data Type Description
amount read only number The amount of payment.
billing_method read only object The billing method that was used for the payment.
check_number read only string The check number that was used for the payment.
date_charged read only string The date and time when the payment was made.
pay_item_sid read only string The pay item secure ID.
status read only string The invoice payment status. Values accepted in this field are:
  • complete
  • declined
  • error
type read only string The invoice payment type. Values accepted in this field are:
  • balance
  • balance_refund
  • check
  • charge_back
  • check_prepay
  • credit_card
  • credit_card_prepay
  • refund_check
  • refund_credit_card

Invoice Tax Item Object

Attribute Data Type Description
amount read only number The amount of taxes.
jurisdiction read only string The invoice tax jurisdiction. Values accepted in this field are: county, county_local, federal, local, other, state, state_county_local, and unincorporated.
type read only string The invoice tax type. Values accepted in this field are: business_and_occupation_tax, ca_teleconnect_fund, carrier_gross_receipts, district_tax, district_tax_residential, e911_tax, e911_tax_business, e911_tax_pbx_trunk_line, e911_tax_residential, excise_tax, fed_telecommunications_relay_service, fed_universal_service_fund, fed_usf_a_school, federal_excise_tax, franchise_tax, license_tax, license_tax_business, ny_mctd_184a, ny_mctd_186c, optional_telecommunications_infrastructure_maintenance_fee, puc_fee, sales_tax, sales_tax_business, sales_web_hosting, service_tax, special_tax, state_deaf_and_disabled_fund, state_high_cost_fund, state_poison_control_fund, state_universal_service_fund, statutory_gross_receipts, surcharge, telecom_relay_surcharge, telecommunications_assistance_service_fund, telecommunications_infrastructure_fund, telecommunications_infrastructure_maintenance_fee, transit_tax, trs_business, universal_lifeline_telephone_service_charge, universal_service_fund_access_trunk_line, universal_service_fund_business_line, utility_users_tax, and utility_users_tax_business.

Get Invoices

GET /invoices
Returns invoices matching the criteria in the request URL

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

Response 200 status code with a list of Invoice objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "amount": "0.38",
            "amount_due": "0",
            "amount_tax": "0.32",
            "balance_forward": "-0.45",
            "balance_previous": "-351.91",
            "date_billing_period_end": "2019-01-19T23:59:59.000Z",
            "date_billing_period_start": "2018-12-20T00:00:00.000Z",
            "date_charge_expected": "2019-01-19T23:59:59.000Z",
            "date_charged": null,
            "date_created": "2018-12-19T23:30:01.000Z",
            "date_issued": null,
            "display_id": "004",
            "invoice_items": [
                {
                    "amount": "0.37",
                    "country_code": "USA",
                    "date_billing_period_end": "2019-01-19T23:59:59.000Z",
                    "date_billing_period_start": "2018-12-20T00:00:00.000Z",
                    "direction": "inbound",
                    "type": "toll",
                    "usage": 8880
                },
                {
                    "amount": "0.01",
                    "country_code": "USA",
                    "date_billing_period_end": "2019-01-19T23:59:59.000Z",
                    "date_billing_period_start": "2018-12-20T00:00:00.000Z",
                    "direction": "outbound",
                    "type": "toll",
                    "usage": 60
                }
            ],
            "invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
            "paid": false,
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "pay_items": [],
            "status": "open",
            "tax_items": [
                {
                    "amount": "0.32",
                    "jurisdiction": "federal",
                    "type": "fed_universal_service_fund"
                }
            ]
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/invoices?limit=1&offset=1"
    },
    "total": 4
}

This request returns a list of invoices.

GET /invoices

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

Required Scopes

To get information about Invoice objects, the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the invoice should be shown. Values accepted in this field are true and false. The default value is false.

Get Invoice by SID

GET /invoices/{invoice_sid}
Returns an invoice, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/invoices/4169705e-4284-482f-8e72-e962a8aaad9d' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Invoice object

{
    "amount": "0.38",
    "amount_due": "0",
    "amount_tax": "0.32",
    "balance_forward": "-0.45",
    "balance_previous": "-351.91",
    "date_billing_period_end": "2019-01-19T23:59:59.000Z",
    "date_billing_period_start": "2018-12-20T00:00:00.000Z",
    "date_charge_expected": "2019-01-19T23:59:59.000Z",
    "date_charged": null,
    "date_created": "2018-12-19T23:30:01.000Z",
    "date_issued": null,
    "display_id": "004",
    "invoice_items": [
        {
            "amount": "0.37",
            "country_code": "USA",
            "date_billing_period_end": "2019-01-19T23:59:59.000Z",
            "date_billing_period_start": "2018-12-20T00:00:00.000Z",
            "direction": "inbound",
            "type": "toll",
            "usage": 8880
        },
        {
            "amount": "0.01",
            "country_code": "USA",
            "date_billing_period_end": "2019-01-19T23:59:59.000Z",
            "date_billing_period_start": "2018-12-20T00:00:00.000Z",
            "direction": "outbound",
            "type": "toll",
            "usage": 60
        }
    ],
    "invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
    "paid": false,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "pay_items": [],
    "status": "open",
    "tax_items": [
        {
            "amount": "0.32",
            "jurisdiction": "federal",
            "type": "fed_universal_service_fund"
        }
    ]
}

This request returns data for an invoice, targeted by secure ID.

GET /invoices/{invoice_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about an Invoice object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
invoice_sid required string The invoice secure ID.

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the invoice should be shown. Values accepted in this field are true and false. The default value is false.

Get Invoice HTML Report by SID

GET /invoices/{invoice_sid}.html
Returns an invoice, targeted by secure ID, in the HTML format

curl -X GET \
'https://api.carrierx.com/core/v2/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.html' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the invoice in the HTML format

This request returns data for a particular invoice in the HTML format. If the request succeeds, there will be a download link.

GET /invoices/{invoice_sid}.html

Required Scopes

To get an invoice in the HTML format the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
invoice_sid required string The invoice secure ID.

Send Invoice HTML Report by SID to Email Addresses

/invoices/{invoice_sid}.html/emails
Sends an invoice, targeted by secure ID, in the HTML format to the email addresses specified in the request

curl -X POST \
'https://api.carrierx.com/core/v2/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.html/emails' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'emails=john.doe%40mail.com' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code and sends the invoice in the HTML format to an email address

This request sends this particular invoice in the HTML format to the email addresses specified in the request.

/invoices/{invoice_sid}.html/emails

Required Scopes

To send an invoice in the HTML format to an email address the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
invoice_sid required string The invoice secure ID.

Body Arguments

The body contains the list of the email addresses in the URL-encoded format this invoice must be sent to. If several email addresses are passed, they must be separated with commas also in the URL-encoded format.

Get Invoice PDF Report by SID

GET /invoices/{invoice_sid}.pdf
Returns an invoice, targeted by secure ID, in the PDF format

curl -X GET \
'https://api.carrierx.com/core/v2/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.pdf' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the invoice in the PDF format

This request returns data for a particular invoice in the PDF format. If the request succeeds, there will be a download link.

GET /invoices/{invoice_sid}.pdf

Required Scopes

To get an invoice in the PDF format the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
invoice_sid required string The invoice secure ID.

Send Invoice PDF Report by SID to Email Addresses

/invoices/{invoice_sid}.pdf/emails
Sends an invoice, targeted by secure ID, in the PDF format to the email addresses specified in the request

curl -X POST \
'https://api.carrierx.com/core/v2/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.pdf/emails' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'emails=john.doe%40mail.com' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code and sends the invoice in the PDF format to an email address

This request sends this particular invoice in the PDF format to the email addresses specified in the request.

/invoices/{invoice_sid}.pdf/emails

Required Scopes

To send an invoice in the PDF format to an email address the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
invoice_sid required string The invoice secure ID.

Body Arguments

The body contains the list of the email addresses in the URL-encoded format this invoice must be sent to. If several email addresses are passed, they must be separated with commas also in the URL-encoded format.

Lookup

The Lookup API returns data regarding phone numbers and IP addresses.

Phonenumber Lookup Object

Sample Phonenumber Lookup object

{
    "country_code": "USA",
    "details": {
        "carrier": {
            "mcc": null,
            "mnc": null,
            "name": null,
            "type": null
        },
        "cnam": {
            "name": "",
            "type": null
        },
        "lrn": "6466531111"
    },
    "e164_format": "+15162065319",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "phonenumber": "15162065319",
    "state": "NY"
}

This section outlines the Phonenumber Lookup object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute Data Type Description
country_code read only string The ISO 3166-1 alpha-3 code of the country.
details read only object The detail object contains cnam, lrn, and carrier data. Refer to the table below for more information.
e164_format read only string The DID in the E.164 format.
in_country_format read only string The DID in a national format.
international_format read only string The DID in an international format.
phonenumber read only string The phone number.
state read only string Geographic area codes of this DID (for the US DIDs only).

Phonenumber Lookup Detail Object

Attribute Data Type Description
carrier read only object The carrier information for the phone number. Refer to the carrier table for more information.
cnam read only object The cnam information for the phone number. Refer to the cnam table for more information.
lrn read only string The location routing number.

Phonenumber Lookup Detail Carrier Object

Attribute Data Type Description
mcc read only integer The mobile country code.
mnc read only integer The mobile network code.
name read only string The carrier name.
type read only string The type of the DID. Values accepted in this field are: landline, mobile, and unknown.

Phonenumber Lookup Detail Cnam Object

Attribute Data Type Description
name read only string The caller name.
type read only string The caller type.

Get Details for Phone Number

GET /lookup/dids/{phonenumber}
Returns the phone number details

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/15162065319?cnam=true&lrn=true&carrier=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the phone number details

{
    "country_code": "USA",
    "details": {
        "carrier": {
            "mcc": null,
            "mnc": null,
            "name": null,
            "type": null
        },
        "cnam": {
            "name": "",
            "type": null
        },
        "lrn": "6466531111"
    },
    "e164_format": "+15162065319",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "phonenumber": "15162065319",
    "state": "NY"
}

This request returns data for the specified phone number.

GET /lookup/dids/{phonenumber}

This request is enabled for Field Filtering.

Required Scopes

To query information for phone numbers the partner must have the following scopes enabled:

Path Arguments

Parameter Data Type Description
phonenumber required string The phone number to look up.

Query Arguments

Parameter Data Type Description
carrier boolean Determines if the carrier information should be shown. Values accepted in this field are true and false.
cnam boolean Determines if the CNAM information should be shown. Values accepted in this field are true and false.
cnam_ttl integer Overrides the default CNAM cache TTL.
country_code string The ISO 3166-1 alpha-3 code of the country for this phone number.
guess string Optional recommendation whether this number is domestic or not. Values accepted in this field are:
  • e164 for international numbers.
  • north_america for the domestic numbers, which are a part of the North American Numbering Plan (NANP).
The default value is north_america.
lrn boolean Determines if the location routing number should be shown. Values accepted in this field are true and false.

Phone Number Lookup Logic

CarrierX performs the phone number lookup based on the following logic:

If the number could not be matched with any available valid phone numbers, the system will return the 400 error status code. If the number format is invalid, the system will return the 404 error status code.

IP2Location Object

Sample IP2Location object

{
    "city": "Mountain View",
    "common_name": "United States",
    "iso_3166_alpha_2": "US",
    "iso_3166_alpha_3": "USA",
    "region": null,
    "state": "CA"
}

This section outlines the IP2Location object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute Data Type Description
city read only string The IP address city.
common_name read only string The common name of the country the IP address belongs to.
iso_3166_alpha_2 read only string The ISO 3166-1 alpha-2 two-letter code of the country.
iso_3166_alpha_3 read only string The ISO 3166-1 alpha-3 three-letter code of the country.
region read only string The IP address region.
state read only string The IP address state.

Get Details for IP Address

GET /lookup/lookup/ip_addresses/{ip_address}
Returns the IP address details

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/ip_addresses/8.8.8.8' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the IP address details

{
    "city": "Mountain View",
    "common_name": "United States",
    "iso_3166_alpha_2": "US",
    "iso_3166_alpha_3": "USA",
    "region": null,
    "state": "CA"
}

This request returns data for the specified IP address.

GET /lookup/lookup/ip_addresses/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

To query information for IP addresses the partner must have the following scope enabled:

Path Arguments

Parameter Data Type Description
ip_address required string The IP address to look up.

OAuth

OAuth tokens are used in API requests and allow to manage all other Core API objects for which the partner has the appropriate scopes set.

OAuth tokens with the token_type set to bearer are passed in request headers (e.g., -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda') and are used as credentials for the authentication with the API.

The partners with appropriate scopes can generate OAuth tokens both for themselves and for sub-partners, targeting the sub-partners by their secure IDs.

OAuth Token Object

This section outlines the OAuth Token object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample OAuth Token object

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}
Attribute Data Type Description
access_token read only string The access token value to be used in authentication.
client_id read only string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret read only string The client secret string. This is a unique string representing the registration information provided to the client upon request. This field is hidden and not returned in the response.
date_created read only string The date and time when the token was created.
date_expiration_access_token create update string The date and time when the token expires.
date_expiration_refresh_token create update string The date and time when the refresh token expires.
date_last_accessed read only string The date and time when the token was last accessed.
date_last_modified admin read only string The date and time when the token was last modified.
id admin read only integer An internal identifier of the OAuth token.
ip_last_accessed read only string The IP address from which the token was last accessed.
name create update string The friendly name used to identify the token.
partner read only object The Partner object associated with the OAuth token. This field is displayed if with_related is set to true when performing the GET queries.
partner_login admin read only string The partner login to the system used to create this OAuth token.
partner_sid read only string The secure ID of the partner associated with the OAuth token.
refresh_token read only string The refresh token value to create a new token.
scopes create update string The scope of the access request available for this specific token. Any values in scopes must exist in available_scopes on the Partner object. Refer to the available_scopes table for a comprehensive list of scopes that can be assigned to a partner. If this field is not specified when creating an OAuth Token object, all available_scopes from the Partner object are added.
token_sid read only string The token secure ID.
token_type read only string The token type.
visibility admin read only string Whether the partners can access the OAuth token using CarrierX API. Values accepted in this field are:
  • common for the OAuth tokens visible to partners.
  • system for the OAuth tokens visible to the system and administrator users only.

Generate OAuth Bearer Token

/oauth/token
Generates an OAuth bearer token for a partner

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=password&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&username=carrierx_partner&password=qwerty123' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the OAuth Token object

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

This request generates a token for the partner upon request.

/oauth/token
/admin/oauth/token

Required Scopes

To generate an OAuth token the partner must have one of the following scopes enabled:

Body Arguments

Parameter Data Type Description
access_token_expires_in integer The access token expiration in seconds.
client_id required string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret required string The client secret string. This is a unique string representing the registration information provided to the client upon request.
grant_type required string The grant type for the token. Values accepted in this field are:
  • password to generate and access token.
  • refresh_token to refresh an access or refresh token, or create a new access token without the use of credentials.
name string The friendly name used to identify the token.
password required* string The password of the partner (used with grant_type = password).
refresh_token required** string The refresh token (used with grant_type = refresh_token).
refresh_token_expires_in integer The refresh token expiration in seconds.
refresh_token_type string The type of request (used with grant_type = refresh_token). Values accepted in this field are:
  • access_token to refresh the time during which the access token remains valid.
  • new_token to create a new access token without the use of login and password.
  • refresh_token to refresh the time during which the refresh token remains valid.
The default value is access_token.
scope string The list of comma-separated partner scopes available for the generated token.
username required* string The login of the partner (used with grant_type = password).

*These fields are required if the grant_type attribute is set to password.
**This field is required if the grant_type attribute is set to refresh_token.

Generate OAuth Bearer Token for Sub-partner

/oauth/token/{partner_sid}
Generates an OAuth bearer token for a sub-partner

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token/cee93bf3-5746-43fe-a1a2-822c05fef687' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the OAuth Token object

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

This request generates the token for a sub-partner, targeted by secure ID.

/oauth/token/{partner_sid}
/admin/oauth/token/{partner_sid}

Required Scopes

To generate an OAuth token for a sub-partner the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The sub-partner secure ID.

Body Arguments

Parameter Data Type Description
access_token_expires_in integer The access token expiration in seconds.
client_id required string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret required string The client secret string. This is a unique string representing the registration information provided to the client upon request.
name string The friendly name used to identify the token.
refresh_token_expires_in integer The refresh token expiration in seconds.
scope string The list of comma-separated partner scopes available for the generated token.

Revoke OAuth Token

/oauth/revoke
Terminates an OAuth token, targeted by the partner client ID and client secret

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request terminates the session of the partner targeted by cient ID and client secret.

/oauth/revoke
/admin/oauth/revoke

Required Scopes

To revoke an OAuth token the partner must have one of the following scopes enabled:

Body Arguments

Parameter Data Type Description
token string The access token that will be revoked. If no token is specified, the token that is used for the authorization in the current request will be revoked.
client_id required string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret required string The client secret string. This is a unique string representing the registration information provided to the client upon request.
token_type string The token type.

Get All Active OAuth Tokens

GET /oauth/tokens
Returns all active tokens for the logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/tokens' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with token data

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
            "client_id": "5c7965f285344165b003ce1a3202e589",
            "date_created": "2020-09-11T13:46:42.211Z",
            "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
            "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
            "date_last_accessed": null,
            "ip_last_accessed": null,
            "name": "test_token",
            "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
            "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
            "scopes": [
                "accesscontrol.manage",
                "endpoints.manage",
                "oauth.manage",
                "partners.manage",
                "phonenumber.manage",
                "push.manage",
                "shortener.manage",
                "sms.manage",
                "storage.manage",
                "trunk_groups.manage",
                "trunk_groups.trunks.manage"
            ],
            "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
            "token_type": "bearer"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns the tokens of the logged-in partner.

GET /oauth/tokens
GET /admin/oauth/tokens

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

Required Scopes

To get information about OAuth tokens the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the OAuth token should be shown. Values accepted in this field are true and false. The default value is false.

Get OAuth Token by SID

GET /oauth/tokens/{token_sid}
Returns an OAuth token, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/tokens/b3f45e4d-7d46-467b-9724-272f57ac420e' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the OAuth Token object

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

This request returns data for an OAuth token, targeted by secure ID.

GET /oauth/tokens/{token_sid}
GET /admin/oauth/tokens/{token_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about an OAuth token the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
token_sid required string The OAuth token secure ID.

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the OAuth token should be shown. Values accepted in this field are true and false. The default value is false.

Update OAuth Token

PATCH /oauth/tokens/{token_sid}
Updates the OAuth Token object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/tokens/b3f45e4d-7d46-467b-9724-272f57ac420e' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"new_test_token"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated OAuth Token object

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "new_test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

This request updates an OAuth token, targeted by secure ID.

PATCH /oauth/tokens/{token_sid}
PATCH /admin/oauth/tokens/{token_sid}
PUT /oauth/tokens/{token_sid}
PUT /admin/oauth/tokens/{token_sid}

An OAuth Token object can be updated using either a PATCH or PUT request.

Required Scopes

To update an OAuth Token object, the partner must have one of the following scopes enabled:

To update an OAuth Token object scope parameter, the partner must additionally have the oauth.allow_token_scope_update scope enabled.

Path Arguments

Parameter Data Type Description
token_sid required string The OAuth token secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Get Current Partner

GET /oauth/whoami
Returns the currently logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with data about the currently logged-in partner

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes" : [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "balance": "351.53",
    "billing_email": "jsmith@freeconferencecall.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "date_created": "2018-09-20T21:34:55.000Z",
    "display_id": "CX90576809",
    "login": "johnsmith",
    "name": "John Smith",
    "owner_email": "jsmith@freeconferencecall.com",
    "parent_assigned_acls": [],
    "parent_sid": "ac38746e-d2e2-4cd6-29ae-b6658f0728b6",
    "partner_sid": "ed437907-002d-4ecc-aa3a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "5162065319",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "jsmith@freeconferencecall.com",
    "transformations": [],
    "zip": "90804"
}

This request returns the currently logged-in partner.

GET /oauth/whoami
GET /admin/oauth/whoami

Refer to the Partner Object for a full list of the fields that appear in the Partner object.

Partner Login Object

This section outlines the Partner Login object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Partner Login object

{
    "login": "carrierx_partner",
    "login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
    "partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
    "token_scopes": [
        "partners.read",
        "partners.update"
    ]
}
Attribute Data Type Description
login create string The partner additional login (sub-login) to the system.
login_sid read only string The partner login secure ID.
partner_sid read only string The secure ID of the partner associated with the partner sub-login.
password create update string The partner password for the partner sub-login to the system. This field is required to create a Partner Login object, but is hidden in the serialized copy of the Partner Login objects received in responses to the requests for the security reasons.
token_scopes create update array The list of scopes that will be applied to the tokens created with this partner sub-login.
use_on_root_login admin create update boolean Whether this partner sub-login credentials can be used for the parent partner login as well. A partner can use only one sub-login with this attribute set to true. The default value is false.

Create Partner Login

/oauth/logins
Creates a partner sub-login

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/logins' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"carrierx_partner","password":"myStrongPassword123","token_scopes":["partners.read","partners.update"]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Partner Login object

{
    "login": "carrierx_partner",
    "login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
    "partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
    "token_scopes": [
        "partners.read",
        "partners.update"
    ]
}

This request creates an additional login for a partner.

/oauth/logins
/admin/oauth/logins

Required Scopes

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

Body Arguments

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

Required fields to create a partner login are:

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

Get Partner Logins

GET /oauth/logins
Returns partner logins matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/logins' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Partner Login objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "login": "carrierx_partner",
            "login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
            "partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
            "token_scopes": [
                "partners.read",
                "partners.update"
            ]
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of partner logins.

GET /oauth/logins
GET /admin/oauth/logins

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

Required Scopes

To get information about Partner Login objects, the partner must have one of the following scopes enabled:

Get Partner Login by SID

GET /oauth/logins/{login_sid}
Returns a partner login, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Partner Login object

{
    "login": "carrierx_partner",
    "login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
    "partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
    "token_scopes": [
        "partners.read",
        "partners.update"
    ]
}

This request returns data for a partner login, targeted by secure ID.

GET /oauth/logins/{login_sid}
GET /admin/oauth/logins/{login_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Partner Login object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
login_sid required string The partner login secure ID.

Update Partner Login

PATCH /oauth/logins/{login_sid}
Updates the Partner Login object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Content-Type: application/json' \
--data-binary '{"password":"myNewStrongPassword"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated Partner Login object

{
    "login": "carrierx_partner",
    "login_sid": "abcf6b1f-7281-4da9-a4d6-3fb53e3a76de",
    "partner_sid": "edebf627-ebce-4f77-8160-75db76154168",
    "token_scopes": [
        "partners.read",
        "partners.update"
    ]
}

This request updates a partner login, targeted by secure ID.

PATCH /oauth/logins/{login_sid}
PATCH /admin/oauth/logins/{login_sid}
PUT /oauth/logins/{login_sid}
PUT /admin/oauth/logins/{login_sid}

A Partner Login object can be updated using either a PATCH or PUT request.

Required Scopes

To update a Partner Login object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
login_sid required string The partner login secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

The field that can be modified is password.

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

Delete Partner Login

DELETE /oauth/logins/{login_sid}
Deletes a partner login, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/oauth/logins/abcf6b1f-7281-4da9-a4d6-3fb53e3a76de' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes a partner login, targeted by secure ID.

DELETE /oauth/logins/{login_sid}
DELETE /admin/oauth/logins/{login_sid}

Required Scopes

To delete a Partner Login object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
login_sid required string The partner login secure ID.

Partners

A partner is an individual or company with CarrierX credentials. Partners can have sub-partners, each of which is governed by its own set of credentials.

Partner Object

This section goes over the parts of the Partner object. These fields and values make up the JSON object that gets returned with successful requests.

Sample Partner object

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "5",
    "billing_email": null,
    "callbacks": {
        "sms":"https://example.com/sms-callback-url"
    },
    "charge_at": null,
    "city": null,
    "company_name": "ABC",
    "country_code": "USA",
    "date_created": "2019-01-22T17:16:30.844Z",
    "display_id": "CX57121051",
    "login": "john",
    "name": "John Smith",
    "owner_email": null,
    "parent_assigned_acls": [],
    "parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
    "payment_type": "postpay",
    "phonenumber": "180045012323",
    "prepay_amount": null,
    "spending_limit": "100",
    "state": "",
    "status": "unverified",
    "tech_email": null,
    "transformations": [],
    "zip": "90804"
}
Attribute Data Type Description
acls create update array of objects The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information.
address1 create update string The partner address.
address2 create update string The partner address second field.
attributes create update object The partner attributes.
available_scopes read only array The abilities that this specific partner has. This field is for internal use only. Refer to this table for the complete list of available scopes.
balance read only number The current balance of the partner.
billing_email create update string The partner email address used for billing purposes. If this field is empty, the owner_email is used.
callbacks create update object The callback URLs. The allowed callback URL types include:
  • app_conference_call for conference call activity.
  • app_conference_meeting for conference meeting room activity.
  • app_mediator for the activity triggered by Mediator endpoint.
  • sms for text message activity (when an SMS is sent or received).
charge_at create update number The balance value when the prepay account will be charged.
city create update string The partner city.
company_name create update string The partner company name.
country_code create update string The partner country ISO 3166-1 alpha-3 code.
date_created read only string The date and time when the partner was created.
display_id read only string The partner unique ID.
id admin read only integer An internal identifier of the partner.
login create string The login for web and Core API.
name create update string The partner name.
owner_email create update string The partner primary email address.
parent_assigned_acls create update array of objects The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information.
parent_sid create update string The parent partner secure ID.
partner_sid read only string The partner secure ID.
password create update string The partner password for web and Core API. This field is required to create a partner, but is hidden in the serialized copy of the Partner objects received in responses to the requests for the security reasons.
payment_type create string The type of payment. Values accepted in this field are prepay and postpay. Note that the default value is prepay. To change the payment_type, contact technical support at support@carrierx.com.
phonenumber create update string The partner contact phone number.
prepay_amount create update number The charge amount for prepay customers.
spending_limit create number The maximum amount that a partner is allowed to spend on the account.
state create update string The partner state; two-letter abbreviation code.
status read only string The status of the partner. Values accepted in this field are:
  • active for a partner account that is active.
  • canceled for a partner account that was canceled.
  • deleted for a partner account that was removed.
  • suspended for a partner account that has been suspended because balance went lower than acceptable limit.
  • unconfirmed for a partner account that has not been confirmed.
  • unverified for a partner account with an email that has not been verified.
system_attributes admin create update object The partner system-related attributes, enumerated as key-value pairs. Refer to the table below for more information.
tech_email create update string The partner email address used for technical purposes. If this field is empty, the owner_email is used.
transformations create update array of objects The list of transformations that a call will undergo. Refer to the transformations section for more information.
zip create update string The partner zip code.

ACL Object

This object is used with acls and parent_assigned_acls.

Attribute Data Type Description
access_control_rules create update array The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction create update string The direction for the access control list. Values accepted in this field are:
  • any to apply the rules from the list to both sent and received calls and messages.
  • inbound to apply the rules from the list to received calls and messages.
  • outbound to apply the rules from the list to sent calls and messages.
  • undirected to apply the rules from the list to actions with no direction specified.
sms_action_false create update string The action to be executed for SMS messages if no access control rules are applied. Values accepted in this field are accept and reject.
sms_action_true create update string The action to be executed for SMS messages if any access control rules are applied. Values accepted in this field are accept and reject.
voice_action_false create update string The action to be executed for calls if no access control rules are applied. Values accepted in this field are:
  • accept to accept the calls.
  • reject403 to reject the call with the 403 status code.
  • reject503 to reject the call with the 503 status code.
voice_action_true create update string The action to be executed for calls if any access control rules are applied. Values accepted in this field are:
  • accept to accept the calls.
  • reject403 to reject the call with the 403 status code.
  • reject503 to reject the call with the 503 status code.

Create Partner

/partners
Creates a partner

curl -X POST \
'https://api.carrierx.com/core/v2/partners' \
-H 'Content-Type: application/json' \
--data-binary '{"login":"john", "password":"sample_password", "name":"John Smith", "company_name": "ABC", "parent_sid":"", "country_code":"USA", "zip":"90804", "owner_email": "johnsmith@carriex.com", "payment_type": "postpay", "phonenumber": "180045012323", "charge_at": 20, "prepay_amount": "100"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Partner object

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "5",
    "billing_email": null,
    "callbacks": {
        "sms":"https://example.com/sms-callback-url"
    },
    "charge_at": null,
    "city": null,
    "company_name": "ABC",
    "country_code": "USA",
    "date_created": "2019-01-22T17:16:30.844Z",
    "display_id": "CX57121051",
    "login": "john",
    "name": "John Smith",
    "owner_email": null,
    "parent_assigned_acls": [],
    "parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
    "payment_type": "postpay",
    "phonenumber": "180045012323",
    "prepay_amount": null,
    "spending_limit": "100",
    "state": "",
    "status": "unverified",
    "tech_email": null,
    "transformations": [],
    "zip": "90804"
}

This request creates a partner.

/partners

When a partner is created, a verification message is sent to the owner_email, tech_email, and billing_email addresses provided. The email addresses will not appear in the Partner object until the link in the email body has been clicked, thereby confirming the email address and allowing the partner to use CarrierX services.

Required Scopes

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

Body Arguments

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

Required fields to create a partner are:

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

Get Partners

GET /partners
Returns partners matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/core/v2/partners' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Partner objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "acls": [],
            "address1": null,
            "address2": null,
            "attributes": {},
            "available_scopes": [
                "accesscontrol.manage",
                "app.manage",
                "calls.manage",
                "countries.manage",
                "endpoints.manage",
                "invoices.manage",
                "lookup.dids.read",
                "oauth.allow_token_scope_update",
                "oauth.manage",
                "oauth.manage_all_tokens",
                "partners.billing_method.manage",
                "partners.read",
                "partners.update",
                "phonenumber.manage",
                "push.manage",
                "rating.manage",
                "shortener.manage",
                "sms.manage",
                "storage.manage",
                "trunk_groups.manage",
                "trunk_groups.trunks.manage",
                "verification.manage"
            ],
            "balance": "4.4",
            "billing_email": "example@example.com",
            "callbacks": {},
            "charge_at": "20",
            "city": null,
            "company_name": "FreeConferenceCall",
            "country_code": "USA",
            "date_created": "2019-05-20T18:32:37.000Z",
            "display_id": "CX15650613",
            "login": "example",
            "name": "John Smith",
            "owner_email": "example@example.com",
            "parent_assigned_acls": [
                {
                    "access_control_rules": [
                        "41f8b2d4-68e4-42f7-43b7-357a090cb1ab"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": null,
                    "voice_action_false": null,
                    "voice_action_true": "reject403"
                },
                {
                    "access_control_rules": [
                        "50d74234-73c7-4da4-819e-6e34c451ed71"
                    ],
                    "direction": "outbound",
                    "sms_action_false": null,
                    "sms_action_true": "reject",
                    "voice_action_false": null,
                    "voice_action_true": null
                }
            ],
            "parent_sid": "be128456-3098-4564-b0d1-67dbceee265f",
            "partner_sid": "6bace9c5-3eef-4f75-8f48-fb98e04408be",
            "payment_type": "prepay",
            "phonenumber": "8448440707",
            "prepay_amount": "100",
            "spending_limit": "500",
            "state": null,
            "status": "active",
            "tech_email": "example@example.com",
            "transformations": [],
            "zip": "90804"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of partners.

GET /partners
GET /admin/partners

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

Required Scopes

To get information about Partner objects, the partner must have one of the following scopes enabled:

Get Partner by SID

GET /partners/{partner_sid}
Returns a partner, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Partner object

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "date_created": "2018-09-20T21:34:55.000Z",
    "display_id": "CX72521509",
    "login": "example",
    "name": "John Smith",
    "owner_email": "example@example.com",
    "parent_assigned_acls": [
        {
            "access_control_rules": [
                "93525bae-f9a9-446b-b92a-7f421df7a11e"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": "accept",
            "voice_action_false": null,
            "voice_action_true": null
        }
    ],
    "parent_sid": "ac38616e-d2e7-4cd6-99ae-b6658f0728b6",
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "15162065819",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "example@example.com",
    "transformations": [],
    "zip": "90804"
}

This request returns data for a partner, targeted by secure ID.

GET /partners/{partner_sid}
GET /admin/partners/{partner_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Partner object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The partner secure ID.

Update Partner

PATCH /partners/{partner_sid}
Updates the Partner object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Content-Type: application/json' \
--data-binary '{"address1":"4300 E Pacific Coast Hwy"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated Partner object

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "date_created": "2018-09-20T21:34:55.000Z",
    "display_id": "CX72521509",
    "login": "example",
    "name": "John Smith",
    "owner_email": "example@example.com",
    "parent_assigned_acls": [
        {
            "access_control_rules": [
                "93525bae-f9a9-336b-b92a-7f421df7a11e"
            ],
            "direction": "outbound",
            "sms_action_false": null,
            "sms_action_true": "accept",
            "voice_action_false": null,
            "voice_action_true": null
        }
    ],
    "parent_sid": "ac38616e-d2e3-4cd6-99ae-b6658f0728b6",
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0",
    "payment_type": "prepay",
    "phonenumber": "15162065574",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "example@example.com",
    "transformations": [],
    "zip": "90804"
}

This request updates a partner, targeted by secure ID.

PATCH /partners/{partner_sid}
PATCH /admin/partners/{partner_sid}
PUT /partners/{partner_sid}
PUT /admin/partners/{partner_sid}

A Partner object can be updated using either a PATCH or PUT request.

Required Scopes

To update a Partner object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The partner secure ID.

Query Arguments

Parameter Data Type Description
nested_objects string Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

  • acls
  • address1
  • address2
  • attributes
  • billing_email
  • callbacks
  • city
  • company_name
  • name
  • owner_email
  • parent_assigned_acls
  • phonenumber
  • tech_email
  • transformations
  • zip

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

Delete Partner

DELETE /partners/{partner_sid}
Deletes a partner, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes a partner, targeted by secure ID.

DELETE /partners/{partner_sid}

This action is not possible to accomplish until the selected partner owns sub-partners. All sub-partner accounts must be deleted before a parent partner is deleted.

Required Scopes

To delete a Partner object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The secure ID of the partner to be deleted.

Billing Method Object

A billing method is how a partner will pay for services rendered. This section goes over the parts of the Billing Method object. These fields and values make up the JSON response that gets returned when a request is successful.

Sample Billing Method object

{
    "address1":"4300 E Pacific Coast Hwy",
    "address2":"Suite 1",
    "cc_expiration":"022019",
    "cc_number":"8888",
    "city":"Long Beach",
    "country_code":"USA",
    "first_name":"John",
    "last_name":"Smith",
    "phone":"15162065574",
    "state":"CA",
    "type":"visa",
    "zip": "90804"
}
Attribute Data Type Description
address1 create string The customer address.
address2 create string The customer address second field.
cc_cid create string The credit card CID. This field is hidden in the serialized copy of the Billing Method objects received in responses to the requests for the security reasons.
cc_expiration create string The credit card expiration date in the mmyyyy format.
cc_number create string The credit card number.
city create string The customer city.
country_code create string The partner country code.
ec_account_number create string The electronic check account number.
ec_routing_number create string The electronic check routing number.
first_name create string The partner first name.
last_name create string The partner last name.
phone create string The partner phone number.
state create string The customer state in a two-letter abbreviation format.
type create string The type of the billing method. Values accepted in this field are:
  • american_express
  • check
  • diners_club
  • discover_card
  • electronic_check
  • international_maestro
  • jcb
  • master_card
  • visa
  • wire
zip create string The customer zip code.

Register Billing Method

/partners/{partner_sid}/billing_method
Registers a billing method to a specific partner

curl -X POST \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"visa", "cc_number":"4012888818888", "cc_expiration":"022019", "cc_cid":"318", "first_name":"John", "last_name":"Smith", "address1":"4300 E Pacific Coast Hwy", "address2":"Suite 1", "city":"Los Angeles", "state":"CA", "zip":"90804", "country_code":"USA", "phone":"15162065574"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Billing Method object

{
    "address1":"4300 E Pacific Coast Hwy",
    "address2":"Suite 1",
    "cc_expiration":"022019",
    "cc_number":"8888",
    "city":"Long Beach",
    "country_code":"USA",
    "first_name":"John",
    "last_name":"Smith",
    "phone":"15162065574",
    "state":"CA",
    "type":"visa",
    "zip": "90804"
}

This request registers the billing method for a customer.

/partners/{partner_sid}/billing_method

Required Scopes

To register a billing method the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The partner secure ID.

Body Arguments

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

Required fields to create a billing method are:

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

Get Billing Method by Partner SID

GET /partners/{partner_sid}/billing_method
Returns a billing method, targeted by partner secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Billing Method object

{
    "address1": "4300 E Pacific Coast Hwy",
    "address2": "Suite 1",
    "cc_expiration": "022020",
    "cc_number": "8888",
    "city": "Long Beach",
    "country_code": "USA",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "15162065574",
    "state": "CA",
    "type": "visa",
    "zip": "90804"
}

This request returns information registered for the selected partner.

GET /partners/{partner_sid}/billing_method
GET /admin/partners/{partner_sid}/billing_method

This request is enabled for Field Filtering.

Required Scopes

To get information about a Billing Method object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The partner secure ID.

Delete Billing Method

DELETE /partners/{partner_sid}/billing_method
Deletes a billing method associated with the targeted partner secure ID

curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request deletes a billing method of the partner, targeted by secure ID.

DELETE /partners/{partner_sid}/billing_method

When completed, no billing method will be registered for the specified partner.

Required Scopes

To delete a Billing Method object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
partner_sid required string The partner secure ID.

Phone Numbers

Phone numbers rentable through the CarrierX API are called Direct Inward Dialing numbers (DIDs). DIDs can be organized into DID groups.

Refer to the Browse Available DIDs section to query the phone number inventory for available phone numbers and their capabilities.

Prefixes are a sequence of integers added to the beginning of a phone number that will route incoming calls to the desired recipients.

Short codes are short phone numbers used for SMS communications.

DID Object

This section outlines the DID object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample DID object

{
    "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",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}
Attribute Data Type Description
attributes create update object The DID attributes.
callback_url create update string The callback URL to receive events for SMS.
capabilities read only integer This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability:
  • 1 for receiving SMS
  • 2 for sending SMS
  • 4 for voice
  • 8 for receiving MMS
  • 16 for sending MMS
To enable receiving SMS and voice, add 1 and 4 together to make 5. The maximum value for this field is 31 (1 + 2 + 4 + 8 + 16) for all capabilities: SMS (receiving and sending), voice, and MMS (receiving and sending).
classification_sid admin create update string The phone number classification secure ID, which can be set to one of the DID Classification object secure IDs.
country_code read only string The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
date_status_changed admin read only string The date and time when the DID status changed.
did_group_sid create update string The DID group secure ID.
did_sid read only string The DID secure ID.
external_keys admin read only object The external keys assigned to the DID when it is used with an endpoint.
id admin read only integer The DID internal ID.
in_country_format read only string The DID in a national format.
international_format read only string The DID in an international format.
locality read only string The locality or city of the DID.
lrn_sid read only string The secure ID of the Location Routing Number, which this DID belongs to.
name create update string The DID name. The default value is N/A.
ocn admin read only string The operating company number used with this DID.
partner read only object The Partner object associated with the DID. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the DID.
phonenumber create string The phone number for the DID in the E.164 format.
price read only number The price of the DID.
provider_sid admin read only string The secure ID of the provider used with this DID.
source_trunk_group_sid admin read only string The source trunk group secure ID with which this DID is associated.
state read only string The state or province of the DID.
status admin read only string The current DID status. When the DID status change, a new DID history entry is inserted into the database. Values accepted in this field are:
  • aging for DIDs released but not yet available.
  • assigned for DIDs assigned to the partner.
  • available for DIDs available for renting.
  • deleted for DIDs that have been deleted from the system.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
transformations create update array of objects The transformations that are applied to the DID. Refer to the transformations section for more information.
trunk_group_sid create update string The secure ID of the trunk group associated with the DID.
type admin read only string The DID type. The value accepted in this field is phonenumber_did.

Rent DID

/phonenumber/dids
Assigns 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

{
    "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",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request assigns a DID to a partner.

/phonenumber/dids

Required Scopes

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

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.

Query Arguments

Parameter Data Type Description
filter string Restricts the phone number to be rented by some parameters (e.g., capabilities, state, etc.) and returns the first available phone number matching the filter when you do not specify any body arguments.

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

Get DIDs

GET /phonenumber/dids
Returns rented DIDs matching the criteria in the request URL

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

Response 200 status code with a list of DID objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "country_code": "USA",
            "did_group_sid": null,
            "did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
            "in_country_format": "(516) 206-5574",
            "international_format": "+1 516-206-5574",
            "locality": "NEW YORK",
            "lrn_sid": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "phonenumber": "15162065574",
            "price": "0.6",
            "state": "NY",
            "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/dids?limit=1&offset=1"
    },
    "total": 2
}

This request returns a list of DIDs that have been rented.

GET /phonenumber/dids

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

Required Scopes

To get information about DID objects, the partner must have one of the following scopes enabled:

Query Arguments

Parameter Data Type Description
trunk_group_sid string The trunk group secure ID, used to return DIDs only for a specific trunk group.
with_related boolean Determines if the partner information related to the phone number should be shown. Values accepted in this field are true and false. The default value is false.

Get DID by SID

GET /phonenumber/dids/{did_sid}
Returns a DID, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
    "in_country_format": "(516) 206-5574",
    "international_format": "+1 516-206-5574",
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065574",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request returns data for a DID, targeted by secure ID.

GET /phonenumber/dids/{did_sid}
GET /admin/dids/{did_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a DID object, the partner must have one of the following scopes enabled:

Path Arguments

Parameter Data Type Description
did_sid required string The secure ID of the DID.

Query Arguments

Parameter Data Type Description
with_related boolean Determines if the partner information related to the phone number should be shown. Values accepted in this field are true and false. The default value is false.

Update DID

PATCH /phonenumber/dids/{did_sid}
Updates the DID object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"main line"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the updated DID object

{
    "attributes": {
        "name": "main line"
    },
    "callback_url": null,
    "capabilities": 7,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
    "in_country_format": "(516) 206-5574",
    "international_format": "+1 516-206-5574",
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065574",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request updates a DID, targeted by secure ID.

PATCH /phonenumber/dids/{did_sid}
PATCH /admin/dids/{did_sid}
PUT /phonenumber/dids/{did_sid}
PUT /admin/dids/{did_sid}

A DID object can be updated using either a PATCH or PUT request.

Required Scopes

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

Path Arguments

Parameter Data Type Description
did_sid required string The DID secure ID.

Query Arguments

Parameter Data Type Description
nested_objects string Determines if the nested objects fields and values should be replaced. Value accepted in this field is replace.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

  • attributes
  • callback_url
  • did_group_sid
  • name
  • string_key_1
  • string_key_2
  • transformations
  • trunk_group_sid

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

Release DID

DELETE /phonenumber/dids/{did_sid}
Releases a DID, targeted by secure ID, from a partner account

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 204 status code with an empty body

This request releases a DID, targeted by secure ID, from a partner account.

DELETE /phonenumber/dids/{did_sid}

Required Scopes

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

Path Arguments

Parameter Data Type Description
did_sid required string The secure ID of the DID.