Introduction

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.

Refer to the Voice and SMS products page for quick start guides and video tutorials. These hold walk-through instructions on renting phone numbers, as well as configuring SIP trunks, trunk groups, and 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.

For more information, see our Getting Started with Postman Quick Start Guide.

Main Conventions

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

Credentials

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": 2,
  "has_more": false,
  "items": [
      {
          "addresses": [
              {
                  "direction": "any",
                  "ip": "10.1.10.69",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
          "name": "System Gateway",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {},
          "transformations": [],
          "type": "system_gateway",
          "voip_token": null
      },
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flex",
          "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": 2
}

Core API requests require token authentication. With these, you will be able to work with the Core API and retrieve endpoint login credentials for Conference, FlexML, and Mediator. The first step to using the Core API is obtaining a CarrierX account. To do so, please submit a request through our Contact Us page. With these credentials, you can gain access to the Portal, where you will be able to create a Security Token.

Follow the steps on our Create a Security Token quick start guide to create a token. Note that at this time, tokens are only used for the Core API.

Prior to making requests for a Conference, FlexML, or Mediator endpoint, an Application Endpoint needs to be created. See the Configure an Application Endpoint quick start guide for step-by-step instructions on creating an endpoint.

Each of the application endpoints has different login and password values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the error unauthorized.

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. This includes the URL, to which the request will be sent, the request method, the request related headers, and, optionally, a payload.

Request URL

The usual path to the API objects include 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

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

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

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

Sample PATCH request to modify or add 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'

The successful request returns 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 to add 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'

The successful request returns 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 to modify 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'

The successful request returns 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"
}

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

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.

Additional Request Parameters

All CarrierX API requests require authentication. Refer to the section above for more information about obtaining login credentials. Endpoint credentials are passed using HTTP basic authentication. Pagination and filtering parameters are passed as part of the query URL. Object fields and values are added to the request body.

Responses

All responses are returned in the JSON format with a status code. For common errors returned, refer to the HTTP Errors section.

Pagination

This request returns Call objects starting with the second record available, and returns a maximum of 4 records.

curl -X GET \
'https://api.carrierx.com/conference/v1/calls?offset=2&limit=4' \
-u '[your_user_name]:[your_password]'

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

{
  "count": 0,
  "has_more": false,
  "items": [],
  "limit": 4,
  "offset": 2,
  "pagination": {
      "previous": "https://api.carrierx.com/conference/v1/calls?limit=4&offset=0"
  },
  "total": 0
}

The three optional parameters for pagination are: offset, limit, and order. GET requests use these three parameters to dictate how many items should be skipped in the response, the amount of records to return, and in what order the results should appear.

offset determines the amount of items that are skipped in the response. If there are five records and the offset value is 2, the response will not include the first two records. Instead, it will return records for items three through five. The default value for offset is 0, meaning that the first existing item will appear first.

The parameter limit determines how many items are returned in the response. The default limit is 10, meaning that a maximum of ten items will be returned. If the number of items that exist exceeds the limit value, the has_more value in the response will be set to true. Responses also have a total field, which is the total amount of results that match the search criteria. Note that the field total will be null on objects that are uncountable, such as SMS messages.

The last parameter of pagination is order. Two values are accepted for this parameter: asc and desc. asc is short for ascending and is the default order. Enter the field name to be ordered followed by either asc or desc. For example, name desc will return names sorted in reverse-alphabetical order. Since the default is asc, entering just name will sort the results by name in alphabetical order.

The JSON response for a successful query using the pagination parameters offset, limit, and order will include a pagination parameter. The value of pagination will be empty 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 next or previous URLs. These URLs can be used to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL provided in this field.

Pagination Quick Reference

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

Field Filtering

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

curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?exclude_fields=properties' \
-u '[your_user_name]:[your_password]'

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",
            "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

curl -X PATCH \
'https://api.carrierx.com/core/v2/endpoints/f9248515-62b7-40ae-af43-5072280a3757' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_third_party_endpoint_patched"}' \
-H 'x-audit-name: CarrierX User' \
-H 'x-audit-message: My first updated endpoint' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

{
    "audit_message": "My first updated endpoint",
    "audit_username": "CarrierX User",
    "date_insert": "2021-02-26T17:01:01.985Z",
    "entity": "Endpoint",
    "entity_sid": "f9248515-62b7-40ae-af43-5072280a3757",
    "fields": [
        {
            "field_name": "name",
            "new_value": "my_third_party_endpoint_patched",
            "old_value": "my_third_party_endpoint"
        }
    ],
    "method": "PATCH"
}

HTTP Errors

The Core API uses the following HTTP error codes:

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.

Refer to the Batch section of the API for comprehensive information about each of the request types and corresponding returned data.

Callbacks

The CarrierX API enables callbacks to be sent to a URL. This callback is triggered when a specific action occurs, such as when an SMS is sent either inbound or outbound. 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 following is 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 following is 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.

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.

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.

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.

• action is what type of modification will be made. For example, rewrite_to rewrites the destination phone number.

• direction determines to which direction of traffic the transformation will apply. If we set direction to outbound, the specific transformation will apply to outbound communications only.

• operands are the items that are being acted upon. For example, rewrite_to accepts two operands: the value to replace and the value that it is going to be replaced with.

if_match

An example of the 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)

{
    "action": "lookup_cnam",
    "direction": "inbound",
    "operands": [
        true,
        "{{src}}",
        "{{src}}",
        "from"
    ]
}

lookup_rn

An example of the 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)

{
    "action": "prerouting",
    "direction": "inbound",
    "operands": [
        "To",
        "^(\\+?1?516\\d{7})$",
        100
    ]
}

reject

An example of the 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 one operand: reject(reason)

rewrite_from

An example of the 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)

rewrite_from_header_param

An example of the 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)

rewrite_header

An example of the 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)

rewrite_header_parameter

An example of the 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)

rewrite_to

An example of the 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)

rewrite_to_header_param

An example of the 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)

set_header

An example of the 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)

set_header_parameter

An example of the 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)

{
    "action": "stir_sign",
    "direction": "any",
    "operands": [
        "B",
        true
    ]
}

stir_validate

An example of the 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:

• {{stir_attest}} for the attestation level used for the call.
• {{stir_origid}} for the ID of the call originator.
• {{stir_verstat}} for the TN validation result (available values include TN-Validation-Passed, TN-Validation-Failed, and No-TN-Validation).

API Reference

The Core API has the following sections: Access Control, Apps, Audit, Batch, Calls, Countries, Endpoints, Invoices, Lookup, OAuth, Partners, Phone Numbers, Porting, Prerouting, Properties, Push, Rating, Routing, 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"
}

Look Up Effective ACLs for Calls

The following GET request 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'

A successful request will return a 200 response 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.

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:

• accesscontrol.manage
• accesscontrol.read

Query Arguments

Look Up Effective ACLs for SMS

The following GET request 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'

A successful request will return a 200 response 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.

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:

• accesscontrol.manage
• accesscontrol.read

Query Arguments

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

Create Access Control Rule

The following POST request creates a 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'

A successful request will return a 200 response 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.

Required Scopes

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

• accesscontrol.manage
• accesscontrol.create

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:

• entries
• field
• operation
• quantifier

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

• The calling and called field values are specific for voice calls.
• The from_did, to_did, and message field values are specific for SMS.

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

Get Access Control Rules

The following GET request 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'

A successful request will return a 200 response 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.

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:

• accesscontrol.manage
• accesscontrol.read

Get Access Control Rule by SID

The following GET request 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'

A successful request will return a 200 response 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.

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:

• accesscontrol.manage
• accesscontrol.read

Path Arguments

Update Access Control Rule

The following PATCH request 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'

A successful request will return a 200 response 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.

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

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The access control rule secure ID is passed in the query URL, and the values to be modified are passed in the request body.

• A PUT request can be used to update an entire Access Control Rule object. The access control rule secure ID is passed in the query URL, and the entire Access Control Rule object is passed in the request body.

Required Scopes

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

• accesscontrol.manage
• accesscontrol.update

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• entries
• field
• name
• operation
• quantifier
• read_only

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

Delete Access Control Rule

The following DELETE request 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'

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

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

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:

• accesscontrol.manage
• accesscontrol.delete

Path Arguments

{
    "attributes": {
        "hide_origination_did": "true"
    },
    "date_insert": "2020-10-09T10:15:01.000Z",
    "date_start": "2020-10-09T10:12:28.000Z",
    "date_stop": "2020-10-09T10:12:43.000Z",
    "date_talk": "2020-10-09T10:12:32.000Z",
    "direction": "outbound",
    "dr_sid": "2ce7599c-8391-4cc2-8e06-7b832f110e48",
    "dtmf": null,
    "duration": "15",
    "endpoint_sid": "d59fbc20-3fda-4624-b58b-a8a4ef64b0a8",
    "endpoint_type": "mediator",
    "event_type": "dialout",
    "number_dst": "14437317761",
    "number_redirect": "15162065919",
    "number_src": "12029021281",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "reference_sid": "89b3ef2c-222b-4bd7-bc46-084021e5a770",
    "type": "mediator",
    "version": 2
}

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

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attributes": {
                "hide_origination_did": "true"
            },
            "date_insert": "2020-10-09T10:15:01.000Z",
            "date_start": "2020-10-09T10:12:28.000Z",
            "date_stop": "2020-10-09T10:12:43.000Z",
            "date_talk": "2020-10-09T10:12:32.000Z",
            "direction": "outbound",
            "dr_sid": "2ce7599c-8391-4cc2-8e06-7b832f110e48",
            "dtmf": null,
            "duration": "15",
            "endpoint_sid": "d59fbc20-3fda-4624-b58b-a8a4ef64b0a8",
            "endpoint_type": "mediator",
            "event_type": "dialout",
            "number_dst": "14437317761",
            "number_redirect": "15162065919",
            "number_src": "12029021281",
            "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
            "reference_sid": "89b3ef2c-222b-4bd7-bc46-084021e5a770",
            "type": "mediator",
            "version": 2
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": null
}

{
    "audit_message": null,
    "audit_username": null,
    "date_insert": "2021-01-26T17:01:01.985Z",
    "entity": "PhonenumberGroup",
    "entity_sid": "c4fce34c-c797-431d-85ae-b3c23965b9f7",
    "fields": [
        {
            "field_name": "did_group_sid",
            "new_value": null,
            "old_value": "c4fce34c-c797-431d-85ae-b3c23965b9f7"
        }
    ],
    "method": "DELETE"
}

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

{
    "count": 1,
    "items": [
        {
            "audit_message": null,
            "audit_username": null,
            "date_insert": "2021-01-26T17:01:01.985Z",
            "entity": "PhonenumberGroup",
            "entity_sid": "c4fce34c-c797-431d-85ae-b3c23965b9f7",
            "fields": [
                {
                    "field_name": "did_group_sid",
                    "new_value": null,
                    "old_value": "c4fce34c-c797-431d-85ae-b3c23965b9f7"
                }
            ],
            "method": "DELETE"
        }
    ],
    "has_more": false,
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": null,
}

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

Error Detail Object

status

Create Task

The following POST request 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'

A successful request will return a 200 response 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.

Required Scopes

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

• batch.manage
• batch.create

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:

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

Get Tasks

The following GET request 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'

A successful request will return a 200 response 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.

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:

• batch.manage
• batch.read

Get Task by SID

The following GET request 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'

A successful request will return a 200 response 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.

Required Scopes

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

• batch.manage
• batch.read

Path Arguments

Update Task

The following PATCH request 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'

A successful request will return a 200 response 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.

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

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The task secure ID is passed in the query URL, and the values to be modified are passed in the request body.

• A PUT request can be used to update an entire Task object. The task secure ID is passed in the query URL, and the entire Task object is passed in the request body.

Required Scopes

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

• batch.manage
• batch.update

Path Arguments

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

The following DELETE request 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'

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

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

Required Scopes

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

• batch.manage
• batch.delete

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

Batch Review Item Object

Get Task Review Items by SID

The following GET request 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'

A successful request will return a 200 response 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.

Required Scopes

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

• batch.manage
• batch.read

Path Arguments

Download CSV of Task Review Items by SID

The following GET request returns task review items for a partner in 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'

A successful request will return a 200 response and a CSV download.

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

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:

• batch.manage
• batch.read

Path Arguments

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:

{
    "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",
    "sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
    "sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
    "sipcause": "200",
    "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",
    "version": 2
}

Get Call Detail Records

The following GET request returns call detail records matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Call Detail Record objects.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "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",
            "sipcallid_dst": "11b5b29c3486cac52a7d5baa52c937c9@12.7.193.174",
            "sipcallid_src": "428ac5df4582bea66501f7d45199a18d@162.251.180.24",
            "sipcause": "200",
            "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",
            "version": 2
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/calls/call_drs?limit=1&offset=1"
    },
    "total": null
}

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

This request is enabled for Pagination, 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:

• calls.manage
• calls.read