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 the App. Click Run in Postman to import this collection to the Postman app.

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

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 Core API has the following base URL:
https://api.carrierx.com/core/v2

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' \
-H 'Accept: 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' \
-H 'Accept: 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' \
-H 'Accept: 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:

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.
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.
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.
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

Parameter	Data Type	Description
limit	integer	The number of items to be shown in the response. The value entered should not exceed `1000`. `10` is the default value. This parameter and value are added to the query URL.
offset	integer	The amount of items skipped in the response. `0` is the default value. This parameter and value are added to the query URL.
order	string	The name of the field to be ordered followed by the order of the response data, either `asc` or `desc`. The field to be ordered is listed first, followed by the order value. For example: `binding_sid desc`. `asc` is the default order. This parameter and values are added to the query URL.

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
eq	equal to. This search looks for the exact value entered. In the example, results will have the exact `"my_mediator"` value for the `name` field.	`name eq "my_mediator"`
ge	greater than or equal to. This search returns records where the value is greater than or equal to the field listed. For example, records are returned where the value of `wait_origination_did_ttl` is greater than or equal to `70000`.	`wait_origination_did_ttl ge 70000`
gt	greater than. This search returns records where the value is exceeded for the field listed. For example, records are returned where the value of `maximum_ttl` is greater than `40000`.	`maximum_ttl gt 40000`
ilike	same functionality as `like` but case insensitive.	`name like "AccOUnt%"`
in	the current value of the specified field must be contained within the specified list. The following example will return records that have a `status` value of either `"active"` or `"suspended"`.	`status in ("active", "suspended")`
le	less than or equal to. This search returns records where the value is less than or equal to the field listed. For example, records are returned where `wait_origination_did_ttl` is less than or equal to `90000`.	`wait_origination_did_ttl le 90000`
like	contains the value indicated in the string passed. `%` can be added anywhere as part of the string to indicate that there can exist text before or after the string parts. In the example, the command looks for a name starting with “Account”. This form of search is case sensitive. Note that this method of search will also work: `name like "A%t"`, and this search will yield records with name values beginning with `A` and ending in `t`.	`name like "Account%"`
lt	less than. This search returns records where the value is less than the field listed. For example, records are returned where `maximum_ttl` is less than `10000`.	`maximum_ttl lt 10000`
ne	not equal to. This search returns records that do not include the `"my_mediator"` value for the `name` field.	`name ne "my_mediator"`
notin	not in. The current value of the specified field must not be in the specified list. The following example will return records that do not have a `status` value of `"active"`.	`status notin ("active")`

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

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.

HTTP Errors

The Core API uses the following HTTP error codes:

Error Code	Message	Description
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 content type JSON.
500	Internal server error	The server encountered an unexpected condition which prevented it from fulfilling the request.

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 new batch task, you will have the option to review the items if you set the review field to boolean value true. 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.

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

{
  "dr_sid":"2a217f8d-df41-4e3d-bece-c72eaa2a8e2a",
  "version":2,
  "type":"mediator",
  "partner_sid":"ed437757-002d-4ecc-aa5a-efdf5e50dba0",
  "direction":"inbound",
  "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",
  "number_src":"15162065345",
  "number_dst":"15162065344",
  "number_redirect":"15162065346",
  "duration":45,
  "endpoint_sid":"632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
  "endpoint_type":"mediator",
  "event_type":"binding",
  "reference_sid":"05561bef-ce48-4823-a847-bf10f7837a42",
  "dtmf":null,
  "attributes":{}
}

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 Call 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 will 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.

By default, only X- headers can be added and updated.

Attribute	Data Type	Description
action	string	The action to be executed for the transformation. See the table for a list of all actions.
direction	string	The direction of communication that the transformation applies to. Values accepted in this field are: `inbound`, `outbound`, and `any`.
operands	array	The values to be transformed. Operands can include set values or regex.

action

Attribute	Data Type	Description
lookup_rn	string	This attribute is used to lookup the routing number. Accepts nine items: Force lookup mode (`true`/`false`, default is `false`). 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. Always include the routing number (`true`/`false`, default is `false`). 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 phone number to look up (default `{{dst}}`). Usually `{{dst}}` (destination) to look up the routing number for the called party or `{{src}}` (source) for the calling party. The destination field where the routing number will be stored (default is `to`). 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 behavior on transformation request failure (`die`/`original_npdi_or_die`/`ignore`, default is `die`). The destination number input format (`guess`/`ignore_plus`/`e164`, default is `guess`). Output format for domestic numbers (`domestic`/`e164`/`e164_with_plus`, default is `domestic`). Output format for international numbers (`e164`, `e164_with_plus`, `passthrough`, default is `passthrough`). Output format if the destination number input format is `guess` and no lookup routing number was found (`domestic`/`e164`/`e164_with_plus`/`passthrough`, default is `passthrough`, non-default values will be applied only if `always` is set to `true`).
rewrite_from	string	Accepts two items: the value to be replaced and what it will be replaced with. This attribute is used to rewrite the phone number of the incoming call.
rewrite_from_header_param	string	Accepts three items: the `from_header` to change, the value to be replaced, and what it will be replaced with. This attribute is used to change `from_header`.
rewrite_header	string	Accepts four items: the header, pattern, new value, and default value.
rewrite_header_parameter	string	Accepts five items: header, parameter, pattern, replace value, and default value.
rewrite_to	string	Accepts two items: the value to be replaced and what it will be replaced with. This attribute is used to rewrite the destination phone number.
set_header	string	Accepts two items: the value to be replaced and what it will be replaced with. This attribute is used to set a header. If the value is set to an empty string and there is a pre-existing header, it will be cleared.
set_header_parameter	string	Accepts three items: the header, parameter, and new value.

API Reference

The Core API has the following objects: Access Control, Calls, Countries, Endpoints, Invoices, Lookup, OAuth, Partners, Phone Numbers, Push, 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.

Attribute	Data Type	Description
access_control_rules	array	The list of Access Control Rule secure IDs. See the Access Control Rule Object for more information about Access Control Rules.
direction	string	The direction for the Access Control List. Values accepted in this field are: `inbound`, `outbound`, and `any`.
sms_action_false	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	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	string	The action to be executed for calls if no Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `reject503`.
voice_action_true	string	The action to be executed for calls if any Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `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 serialized copy of the Access Control List object.

{
    "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 the trunk group. Note that effective ACLs are executed from the most top-level object. This request is enabled for Field Filtering.

Method	URL
GET	/accesscontrol/effective_acl/calls

Query Arguments

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

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 serialized copy of the Access Control List object.

{
    "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 the partner or trunk group, targeted by secure ID. Note that effective ACLs are executed from the most top-level object. This request is enabled for Field Filtering.

Method	URL
GET	/accesscontrol/effective_acl/sms

Query Arguments

Parameter	Data Type	Description
direction	string	The direction for the Access Control List. Values accepted in this field are: `inbound`, `outbound`, and `any`.
partner_sid	string	The partner secure ID.
trunk_group_sid	string	The trunk group 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.

Attribute	Data Type	Description
entries	string	The list of entries to compare against the `quantifier` field.
field	string	The field to check. This value will be used in comparison with `entries`.
name	string	The Access Control Rule name. `name` will be set to `N/A` if not specified otherwise.
operation	string	Determines how the value is checked. Values accepted in this field are: `prefix`, `exact`, `regexp`, and `builtin`.
quantifier	string	The type of comparison to be made between `entries` and `field`. Values accepted in this field are `all`, `any`, and `none`.
read_only	boolean	Shows whether the Access Control Rule can be modified or not. Values accepted in this field are `true` and `false`.
rule_sid	string	The Access Control Rule secure ID.

Create Access Control Rule

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

Method	URL
POST	/accesscontrol/rules

Body Arguments

JSON representation of the fields and values of the Access Control Rule to be created. Required fields to create a new object are:

entries
field
operation
quantifier

The field parameter should contain the value against which messages or calls will be checked. Field values calling and called are specific for voice calls. Field values from_did, to_did, and message are specific for SMS.

To view all fields that appear in the Access Control Rule object, see the Access Control Rule Object.

Get Access Control Rules

The following GET request returns Access Control Rules.

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 serialized copy of the Access Control Rule object.

{
    "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.

Method	URL
GET	/accesscontrol/rules

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 information 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.

Method	URL
GET	/accesscontrol/rules/{rule_sid}

Path Arguments

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

Update Access Control Rule

The following PATCH request updates the values passed 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 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"
}

An Access Control Rule object can be updated through PATCH and PUT requests. A PATCH request requires that the rule secure ID passed in the query URL, and the specific parameters and values to be updated be passed in the query body. A PUT request requires the rule secure ID passed in the query URL, as well as the entire ACR object passed in the query body.

Note that read_only must be set to false in order to be able to update an Access Control Rule.

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

Path Arguments

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

Body Arguments

JSON representation of the fields to update.

Fields that can be changed are:

entries
field
name
operation
quantifier
read-only

To view the fields that appear in the ACR object, see the Access Control Rule Object.

Delete Access Control Rule

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

Method	URL
DELETE	/accesscontrol/rules/{rule_sid}

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.

Attribute	Data Type	Description
data	string	The payload for this request. This field should be empty for `DELETE`.
date_created	string	The date when the task was created.
date_modified	string	The date when the task was modified.
entries	string	This is based on `field`. Determines the existing entry. This value should be empty for `POST`.
error_details	array	The error operation details, referenced with entry for `PATCH` and `DELETE` requests.
failure	integer	The count of unsuccessful operations.
field	string	The field used to determine the existing entry. This value only applies to the methods `PATCH` and `DELETE`. The value should be empty for `POST`.
method	string	The method used for the request, either `POST`, `PATCH`, or `DELETE`.
partner_sid	string	The partner secure ID.
processed	integer	The count of processed operations.
status	string	The status for the current task. See the table below for a comprehensive list of statuses.
success	integer	The count of successful operations.
task_sid	string	The task secure ID.
total	integer	The total count of operations.
type	string	The type of task, either `phonenumber` or `prefix`.

status

Attribute	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.
queue	The task is in queue.
running	The task is currently running.

Create Task

The following POST request will create 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 201 response code with a serialized copy of the Task object.

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

This request creates a batch task.

Method	URL
POST	/batch/tasks

Body Arguments

JSON representation of the fields and values of the batch task to be created. Required fields to create a new batch task are method, type, and field.

To view all fields that appear in the Batch object, see 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 serialized copy of the Task objects associated with the credentials.

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

This request returns a list of tasks. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/batch/tasks

Get Task by SID

The following GET request returns a batch task, targeted by task 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.

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

This request returns information about a batch task, targeted by secure ID.

Method	URL
GET	/batch/tasks/{task_sid}

Path Arguments

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

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

This request returns task review items, targeted by task secure ID.

Method	URL
GET	/batch/tasks/{task_sid}/review_items

Path Arguments

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

Download CSV of Task Review Items by SID

The following GET request returns a CSV download.

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.

Method	URL
GET	/batch/tasks/{task_sid}/review_items.csv

Path Arguments

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

Update Task by SID

The following PATCH request updates a batch task.

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 Task object.

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

This request updates a Task object. An object can be updated using PATCH and PUT requests. A PATCH request is used to update one or more attribute values. A PUT request is used to update the whole object.

Method	URL
PATCH	/batch/tasks/{task_sid}
PUT	/batch/tasks/{task_sid}

Path Arguments

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

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.

Delete Task by SID

The following DELETE request deletes a batch task.

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.

Method	URL
DELETE	/batch/tasks/{task_sid}

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.

Attribute	Data Type	Description
date_insert	string	The date when the detail record was inserted into the database.
date_start	string	The date and time when the call was started or the SMS was created.
date_stop	string	The date and time when the call or SMS was delivered.
date_talk	string	The date and time when the destination phone number answered.
direction	string	The direction of the call, either `inbound` or `outbound`.
disconnect_originator	string	The originator of a call drop. The value will be `null` for SMS.
dr_sid	string	The secure ID of the record.
duration	integer	The call duration in seconds.
duration_billing	integer	The calculated call duration in seconds to set the price.
endpoint_sid_dst	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	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	string	The real phone number that the call is coming from. This field is populated from either PAI or RPID.
ip_dst	string	The IP address of the destination of call.
ip_src	string	The IP address of the source of call.
number_billing	string	The subscriber phone number.
number_dst	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	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	string	The destination phone number after any transformations were applied. This field will populate if this value is different from `number_dst`.
number_external	string	The non-subscriber phone number.
number_src	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	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	string	The source phone number after any transformations were applied. This field will populate if this value is different from `number_src`.
partner_sid	string	The partner secure ID.
price	string	The price for the detail record.
ref_id	string	The internal ID of the call.
sipcallid_dst	string	The SIP call ID of the destination call.
sipcallid_src	string	The SIP call ID of the source of call.
sipcause	string	The SIP code of the call.
trunk_group_sid_dst	string	The destination trunk group secure ID.
trunk_group_sid_src	string	The source trunk group secure ID.
trunk_sid_dst	string	The destination trunk secure ID.
trunk_sid_src	string	The source trunk secure ID.
type	string	The type of call. Values accepted in this field are: `telecom`, `sms`, `conference`, and `application`.
version	integer	The version of the detail record as it comes from the resource.

Get Call Detail Records

The following GET request returns call detail records.

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 serialized copy of the Call Detail Record object.

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

Method	URL
GET	/calls/call_drs

Get Call Detail Record by SID

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

A successful request will return a 200 response code with a serialized copy of the 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",
    "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
}

This request returns data for a Call Detail Record, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/calls/call_drs/{dr_sid}

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.

Parameter	Data Type	Description
active	string	Whether or not that rate is effective, as determined by `effective_date`.
effective_date	string	The date when the rate becomes effective.
items	object	The rate details. Refer to the table below for more information.
partner_sid	string	The partner secure ID.
rates_plan	object	The rates plan. Refer to the table below for more information.

items

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

rates_plan

Parameter	Data Type	Description
name	string	The name of the rates plan.
rates_plan_sid	string	The rates plan secure ID.

Get Inbound PSTN Rates

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

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

The request returns a list of inbound PSTN rates for calls. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/calls/rates/inbound/pstn

Download CSV of Inbound PSTN Rates

The following GET request returns a CSV download.

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/pstn/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 inbound PSTN rates matching the request criteria. This request is enabled for Field Filtering.

Method	URL
GET	/calls/rates/inbound/pstn/csv

Get Inbound VoIP Rates

The following GET request returns inbound VoIP rates for calls, targeted by the conference type.

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

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

The request returns a list of inbound VoIP rates for calls, targeted by the endpoint type. This request is enabled for Pagination, Result Filtering, and Field Filtering.

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

Download CSV of Inbound VoIP Rates

The following GET request returns a CSV download.

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

A successful request will return a CSV download.

This request returns a CSV of all inbound VoIP rates matching the request criteria. This request is enabled for Field Filtering.

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

Get Outbound PSTN Rates

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

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

The request returns a list of outbound PSTN rates for calls. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/calls/rates/outbound/pstn

Download CSV of Outbound PSTN Rates

The following GET request returns a CSV download.

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

A successful request will return a CSV download.

This request returns a CSV of all outbound PSTN rates matching the request criteria. This request is enabled for Field Filtering.

Method	URL
GET	/calls/rates/outbound/pstn/csv

Get Outbound VoIP Rates

The following GET request returns outbound VoIP rates for calls.

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

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

The request returns a list of outbound VoIP rates for calls, targeted by endpoint type. This request is enabled for Pagination, Result Filtering, and Field Filtering.

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

Download CSV of Outbound VoIP Rates

The following GET request returns a CSV download.

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

A successful request will return a CSV download.

This request returns a CSV of all outbound PSTN rates matching the request criteria. This request is enabled for Field Filtering.

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

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.

Attribute	Data Type	Description
capital	string	The capital of the country.
common_name	string	The common name of the country.
dialing_prefix	string	The telephone code of the country.
domain	string	The Internet domain of the country.
iso_3166_alpha_2	string	The ISO 3166-1 alpha-2 code of the country.
iso_3166_alpha_3	string	The ISO 3166-1 alpha-3 code of the country.
iso_3166_numeric	string	The ISO 3166-1 numeric code of the country.
mcc	integer	The mobile country code.
official_name	string	The official name of the country.
region	string	The region of the country.
subregion	string	The subregion of the country.

Get Countries

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

A successful request will return a 200 response code with a serialized copy of the Country object.

{
    "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. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/countries

Get Country by ISO Code

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

A successful request will return a 200 response 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. This request is enabled for Field Filtering.

Method	URL
GET	/countries/{country_code}

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

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

A successful request will return a 200 response 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. This request is enabled for Field Filtering. Contact technical support at support@carrierx.com to enable searching for countries by IP address.

Method	URL
GET	/countries/ip/{ip_address}

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.

Attribute	Data Type	Description
addresses	object	The endpoint addresses. Refer to the table below for more information.
allow_custom_caller_id	boolean	Whether or not to allow custom caller ID.
attributes	object	The endpoint attributes. Refer to the table below for more information.
auth_required	boolean	Whether or not auth is required.
capacity	integer	The maximum number of simultaneous inbound and outbound calls.
endpoint_sid	string	The endpoint secure ID.
insecure_addr	string	The insecure address.
name	string	The endpoint name.
out_sip_password	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 addresses object.
out_sip_username	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 addresses object.
partner_sid	string	The secure ID of the partner associated with the endpoint.
properties	object	The endpoint properties. Refer to the table below for more information.
transformations	array	The transformations that apply to the endpoint. Refer to the transformations section for more information.
type	string	The type of endpoint. Values accepted in this field are: `conference playback` for hosted Conference Playback endpoint `conference` for hosted Conference endpoint `flexml` for hosted FlexML endpoint `mediator` for hosted Mediator endpoint `system_gateway` for the CarrierX gateway. This endpoint is created automatically when a new partner is created. The endpoint is not modifiable `third_party` for Third Party endpoint `voicemail` for hosted Voicemail endpoint
voip_token	string	The endpoint authentication token.

addresses

Attribute	Data Type	Description
direction	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	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.
ip	string	The IP address.
port	integer	The port. The default port value is `5060`.
sip_password	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	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.
transport	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 Mediator endpoint.

attributes

Attribute	Data Type	Description
account_sid	string	The account secure ID. This field applies to the mediator endpoint.
api_url	string	The URL to the Mediator swagger. This field cannot be modified. This field applies to the Mediator endpoint.
did_group_id	string	The DID group ID. This field applies to the FlexML and Conference endpoints.
key	string	The attribute key.
subscriber_sid	string	The subscriber secure ID. This field applies to the FlexML and Conference endpoints.
value	string	The attribute value.

properties

Attribute	Data Type	Description
account_sid	string	The account secure ID.
api_url	URL	The URL of the API.
callback_method	string	The callback method used with the Voicemail endpoint. Values accepted in this field are `POST` and `GET`. The default value is `POST`.
callback_url	string	The callback URL used with the Voicemail endpoint. The default value is `null`.
container_sid	string	The secure ID of the container where recordings will be stored. The default value is `null`.
greeting	string	The name of the file used as a greeting for the Voicemail endpoint. The default value is `null`.
login	string	The login for the endpoint.
password	string	The password for the endpoint.

Create Endpoint

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

A successful request will return a 200 response code with an 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
}

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

A successful request will return a 200 response code with an endpoint object.

{
    "addresses": [
        {
            "direction": "any",
            "ip": "1.1.2.13",
            "port": 5060,
            "sip_password": null,
            "sip_username": null,
            "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 a new endpoint. For the Mediator, Conference, Conference Playback, and FlexML endpoints, only the name and capacity values can be edited after the endpoint has been created.

Method	URL
POST	/endpoints

Body Arguments

JSON representation of the fields and values of the endpoint to be created. The required field to create a new 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.

To view all fields that appear in the Endpoint object, see the Endpoint Object.

Get Endpoints

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object.

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "addresses": [
                {
                    "direction": "any",
                    "ip": "1.1.2.13",
                    "port": 5060,
                    "sip_password": null,
                    "sip_username": null,
                    "transport": "udp"
                }
            ],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac",
            "name": "EP_\u0422_1",
            "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"
        },
        {
            "addresses": [
                {
                    "direction": "any",
                    "ip": "1.1.2.13",
                    "port": 5060,
                    "sip_password": null,
                    "sip_username": null,
                    "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": 2
}

This request returns a list of endpoints. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/endpoints

Get Endpoint by SID

The following GET request returns an endpoint matching the 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'

A successful request will return a 200 response code with a serialized copy of the Endpoint object.

{
    "addresses": [
        {
            "direction": "any",
            "ip": "1.1.2.13",
            "port": 5060,
            "sip_password": null,
            "sip_username": null,
            "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 information about an endpoint, targeted by secure ID.

Method	URL
GET	/endpoints/{endpoint_sid}

Path Arguments

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

Update Endpoint

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object.

{
    "addresses": [
        {
            "direction": "any",
            "ip": "1.1.2.13",
            "port": 5060,
            "sip_password": null,
            "sip_username": null,
            "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"
}

An endpoint can be updated using PATCH and PUT requests. 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 will be updated. All other attributes and values will remain the same. The endpoint secure ID is passed in the query URL, and the parameters are passed in the request body.

Method	URL
PATCH	/endpoints/{endpoint_sid}
PUT	/endpoints/{endpoint_sid}

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated. Note that for Mediator, FlexML, and Conference endpoints, only the name and capacity fields can be updated.

To view all fields that appear in the Endpoint object, see the Endpoint Object.

Delete Endpoint

The following DELETE request deletes the endpoint matching the targeted 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'

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

This request deletes an endpoint from a partner account. Note that the System Gateway endpoint, which is automatically generated when a new partner is created, should not be deleted.

Method	URL
DELETE	/endpoints/{endpoint_sid}

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.

Attribute	Data Type	Description
amount	integer	The amount on the invoice. This is not necessarily due at this time.
amount_due	integer	The amount due.
amount_tax	integer	The tax amount due.
balance_previous	integer	The previous balance on the invoice.
date_billing_period_end	string	The date when the billing period ends.
date_billing_period_start	string	The date when the billing period begins.
date_charge_expected	string	The date when the invoice will be charged.
date_charged	string	The date when the invoice was charged.
date_created	string	The date when the invoice was created.
date_issued	string	The date that the invoice was issued.
display_id	string	The ID on the rendered invoice.
invoice_items	array	The details about each of the invoice items. See the table below for more information.
invoice_sid	string	The invoice secure ID.
paid	boolean	Shows if the invoice has been paid. Values accepted in this field are: `true` and `false`.
partner_sid	string	The secure ID of the partner associated with the DID.
pay_items	string	The payments made while the invoice was open.
status	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	array	The tax items details.

invoice_items

Attribute	Data Type	Description
amount	string	The invoice item price total.
date_billing_period_end	string	The date and time when the billing period ended.
date_billing_period_start	string	The date and time when the billing period started.
direction	string	The direction of the call or SMS/MMS, either `inbound` or `outbound`.
type	string	The type of call or SMS/MMS. Values accepted in this field are: `adjustment` `bridge` `did` `did_lookup_carrier` `did_lookup_cnam` `did_lookup_lrn` `mms` `sms` `toll` `toll_free`
usage	int	The number of times the item was used.

Get Invoices

The following GET request returns invoices.

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

A successful request will return a 200 response code with a serialized copy of the Invoice object.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "amount": "0.38",
            "amount_due": "0",
            "amount_tax": "0",
            "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",
                    "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": []
        }
    ],
    "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. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/invoices

Get Invoice by SID

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

A successful request will return a 200 response code with a serialized copy of the Invoice object.

{
    "amount": "0.38",
    "amount_due": "0",
    "amount_tax": "0",
    "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",
            "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": []
}

This request returns data for an invoice, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/invoices/{invoice_sid}

Path Arguments

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

Get Invoice HTML Report by SID

The following GET request returns an invoice in HTML format, targeted by secure ID.

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

This request returns an invoice in HTML format.

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

Method	URL
GET	/invoices/{invoice_sid}.html

Path Arguments

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

Lookup

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

Get Details for Phone Number

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

A successful request will return a 200 response code with 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"
}

You need the lookup.dids scope enabled for the partner to be able to query information for phone numbers. Contact technical support at support@carrierx.com to enable this option.

This request returns data for the specified phone number. This request is enabled for Field Filtering.

Method	URL
GET	/lookup/dids/{phonenumber}

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`.
lrn	boolean	Determines if the local routing number should be shown. Values accepted in this field are `true` and `false`.

Response Object

Attribute	Data Type	Description
country_code	string	The ISO 3166-1 alpha-3 code of the country.
details	object	The detail object contains `cnam`, `lrn`, and `carrier` data. Refer to the table below for more information.
e164_format	string	The DID in e164 format.
in_country_format	string	The DID in national format.
international_format	string	The DID in international format.
phonenumber	string	The phone number.
state	string	The DID state.

carrier

Attribute	Data Type	Description
mcc	integer	The mobile country code.
mnc	integer	The mobile network code.
name	string	The carrier name.
type	string	The type of the DID. For example, “landline”.

cnam

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

details

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

Get Details for IP Address

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

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

You need the lookup.ip_addresses scope enabled for the partner to be able to query information for IP addresses. Contact technical support at support@carrierx.com to enable this option.

This request returns data for the specified IP address. This request is enabled for Field Filtering.

Method	URL
GET	/lookup/lookup/ip_addresses/{ip_address}

Path Arguments

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

Response Object

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

OAuth

For this request, either the Core API credentials can be used, or any credentials belonging to a sub-account. To access resources of another partner, use the partner_sid and access_code belonging to that partner.

OAuth 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. Note that the fields below are returned as objects inside an items array.

Attribute	Data Type	Description
access_token	string	The access token.
date_created	string	The date when the token was created.
date_expiration_access_token	string	The date when the token expires.
date_expiration_refresh_token	string	The date when the refresh token expires.
date_last_accessed	string	The date when the token was last accessed.
expires_in	string	The number of seconds during which the token will be valid.
ip_last_accessed	string	The IP address from which the token was last accessed.
name	string	The friendly name used to identify the token.
partner_sid	string	The partner secure ID.
refresh_token	string	The refresh token.
scopes	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 a Token object, all `available_scopes` from the Partner object are added.
token_sid	string	The token secure ID.
token_type	string	The token type.

Revoke OAuth Token

The following POST request terminates an OAuth token targeted by token.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke/{token}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This request terminates the session of the partner whose token is specified.

Method	URL
POST	/oauth/revoke/{token}

Path Arguments

Parameter	Data Type	Description
token `required`	string	The access token.

Query Arguments

Parameter	Data Type	Description
client_id	string	The client ID.
client_secret	string	The client secret.
token_type	string	The token type.

Generate OAuth Bearer Token

The following POST request generates an OAuth bearer token.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token?grant_type=password&client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c&username=carrierx_test&password=carrierx_test_pwd&scope=trust' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with token data.

{
  "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
  "token_type": "bearer",
  "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
  "expires_in": 599,
  "scope": "trust"
}

This request generates the token for a partner upon request.

Method	URL
POST	/oauth/token

Query Arguments

Parameter	Data Type	Description
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: `authorization_code`, `password`, and `refresh_token`.
password `required`	string	The password of the partner.
scope `required`	string	The scope of the access request available for the client.
username `required`	string	The login of the partner.

Generate OAuth Bearer Token for Subpartner

The following POST request generates an OAuth bearer token.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token?grant_type=password&client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c&username=carrierx_test&password=carrierx_test_pwd&scope=trust' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with token data.

{
  "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
  "token_type": "bearer",
  "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
  "expires_in": 599,
  "scope": "trust"
}

This request generates the token for a sub-partner.

Method	URL
POST	/oauth/token/{partner_sid}

Query Arguments

Parameter	Data Type	Description
access_token_expires_in	integer	In how many seconds the access token will expire.
client_id `required`	string	The client ID.
client_secret `required`	string	The client secret.
name	string	The OAuth token name.
partner_sid `required`	string	The sub-partner secure ID.
refresh_token_expires_in	integer	In how many seconds the refresh token will expire.
scope	string	The OAuth token visibility scope.

Get All Active Tokens

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

A successful request will return a 200 response code with token data.

{
   "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
   "token_type": "bearer",
   "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
   "expires_in": 461,
   "scope": "trust"
}

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

Method	URL
GET	/oauth/token

Get Current Partner

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

A successful request will return a 200 response code with data about the currently logged-in partner.

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "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",
    "available_scopes" : [],
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "system_attributes": {},
    "tech_email": "jsmith@freeconferencecall.com",
    "transformations": [],
    "zip": "90804"
}

This request returns the currently logged-in partner. Refer to the Partner Object for a full list of the fields that appear in the Partner object.

Method	URL
GET	/oauth/whoami

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. By default, sub-partners cannot be created. Contact technical support at support@carrierx.com to request being able to create sub-partners.

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.

Attribute	Data Type	Description
acls	array	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	string	The partner address.
address2	string	The partner address second field.
allow_custom_callerid	boolean	Whether or not to allow custom caller ID.
attributes	object	The partner attributes.
available_scopes	array	The abilities that this specific partner has. This field is for internal use only.
balance	integer	The current balance of the partner.
billing_email	string	The partner email address used for billing purposes. If this field is empty, the `owner_email` is used.
callbacks	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	integer	The balance value when the prepay account will be charged.
city	string	The partner city.
company_name	string	The partner company name.
country_code	string	The partner country ISO 3166-1 alpha-3 code.
date_created	string	The date and time when the partner was created.
display_id	string	The partner unique ID.
login	string	The login for web and Core API. This field is not modifiable.
name	string	The partner name.
owner_email	string	The partner primary email address.
parent_assigned_acls	array	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	string	The parent partner secure ID.
partner_sid	string	The partner secure ID.
password	sting	The partner password.
payment_type	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	string	The partner contact phone number.
prepay_amount	integer	The charge amount for prepay customers.
spending_limit	integer	The maximum amount that a partner is allowed to spend on the account.
state	string	The partner state.
status	string	The status of the partner. Values accepted in this field are: `deleted` for partner was removed `active` for partner is active `canceled` for partner is canceled `suspended` for partner account has been suspended because balance went lower than acceptable limit `unverified` for partner email has not been verified `unconfirmed` for partner has not been confirmed
tech_email	string	The partner email address used for technical purposes. If this field is empty, the `owner_email` is used.
transformations	array	The changes that a call will undergo. Refer to the transformations section for more information.
zip	string	The partner zip code.

available_scopes

Value	Description
accesscontrol.create	The partner can create Access Control objects.
accesscontrol.delete	The partner can delete Access Control objects.
accesscontrol.manage	The partner can create, read, update, and delete Access Control objects.
accesscontrol.read	The partner can read Access Control objects.
accesscontrol.update	The partner can update Access Control objects.
admin.create	The partner can create admin actions.
admin.delete	The partner can delete admin actions.
admin.manage	The partner can create, read, update, and delete admin actions.
admin.read	The partner can read admin actions.
admin.update	The partner can update admin actions.
app.create	The partner can create Application object actions.
app.delete	The partner can delete Application object actions.
app.manage	The partner can create, read, update, and delete Application object actions.
app.read	The partner can read Application object actions.
app.read_descendant	The partner can view Application object detailed records for the inherited partner.
app.update	The partner can update Application object actions.
batch.create	The partner can create Batch actions.
batch.delete	The partner can delete Batch actions.
batch.manage	The partner can create, read, update, and delete Batch actions.
batch.read	The partner can read Batch actions.
batch.update	The partner can update Batch actions.
calls.create	The partner can create Call objects.
calls.delete	The partner can delete Call objects.
calls.manage	The partner can create, read, update, and delete Call objects.
calls.read	The partner can read Call objects.
calls.read_descendant	The partner can view Call object detailed records for the inherited partner.
calls.update	The partner can update Call objects.
countries.create	The partner can create Country objects.
countries.delete	The partner can delete Country objects.
countries.manage	The partner can create, read, update, and delete Country objects.
countries.read	The partner can read Country objects.
countries.update	The partner can update Country objects.
endpoints.create	The partner can create Endpoint objects.
endpoints.delete	The partner can delete Endpoint objects.
endpoints.manage	The partner can create, read, update, and delete Endpoint objects.
endpoints.read	The partner can read Endpoint objects.
endpoints.update	The partner can update Endpoint objects.
invoices.adjustments	The partner can include the adjustments field when creating an Invoice object.
invoices.chargebacks	The partner can include the chargebacks field when creating an Invoice object.
invoices.create	The partner can create Invoice objects.
invoices.credits	The partner can include the credits field when creating an Invoice object.
invoices.delete	The partner can delete Invoice objects.
invoices.immediately_charges	The partner can include the immediate charges field when creating an Invoice object.
invoices.manage	The partner can create, read, update, and delete Invoice objects.
invoices.read	The partner can read Invoice objects.
invoices.refunds	The partner can include the refunds field when creating an Invoice object.
invoices.update	The partner can update Invoice objects.
lookup.dids.allow_carrier	The partner can read phone number carriers.
lookup.dids.allow_cnam	The partner can read phone number cnams.
lookup.dids.allow_lrn	The partner can read phone number lrns.
lookup.dids.read	The partner can read phone numbers.
lookup.ip_addresses.read	The partner can read IP addresses.
oauth.allow_token_scope_update	The partner can update `token.scope` field modification.
oauth.create	The partner can create OAuth token objects.
oauth.delete	The partner can delete OAuth token objects.
oauth.manage	The partner can create, read, update, and delete OAuth token objects.
oauth.manage_all_tokens	If bearer auth is used, allow the partner to create, read, update, and delete tokens. Otherwise, allow the partner to create, read, update, and delete the current token.
oauth.read	The partner can read OAuth token objects.
oauth.update	The partner can update OAuth token objects.
partners.billing_method.create	The partner can create partner Billing Method objects.
partners.billing_method.delete	The partner can delete partner Billing Method objects.
partners.billing_method.manage	The partner can create, read, update, and delete Billing Method objects.
partners.billing_method.read	The partner can read partner Billing Method objects.
partners.billing_method.update	The partner can update partner Billing Method objects.
partners.create	The partner can create Partner objects.
partners.delete	The partner can delete Partner objects.
partners.manage	The partner can create, read, update, and delete Partner objects.
partners.read	The partner can read Partner objects.
partners.skip_email_verifications	The partner can change the `skip_email_verification` field when creating a new Partner object.
partners.skip_partner_review	The partner can change the `skip_partner_review` field when creating a new Partner object.
partners.update	The partner can update Partner objects.
phonenumber.create	The partner can create (rent) Phone Number objects.
phonenumber.delete	The partner can delete Phone Number objects.
phonenumber.emergency.manage	The partner can create, read, update, and delete Emergency objects.
phonenumber.emergency.read	The partner can read Emergency objects.
phonenumber.line_information.manage	The partner can create, read, update, and delete Line Information objects.
phonenumber.line_information.read	The partner can read Line Information objects.
phonenumber.manage	The partner can create, read, update, and delete Phone Number objects.
phonenumber.read	The partner can read Phone Number objects.
phonenumber.update	The partner can update Phone Number objects.
porting.create	The partner can create Porting objects.
porting.delete	The partner can delete Porting objects.
porting.manage	The partner can create, read, update, and delete Porting objects.
porting.read	The partner can read Porting objects.
porting.update	The partner can update Porting objects.
push.create	The partner can create Push objects.
push.delete	The partner can delete Push objects.
push.manage	The partner can create, read, update, and delete Push objects.
push.read	The partner can read Push objects.
push.update	The partner can update Push objects.
rating.create	The partner can create rating actions.
rating.delete	The partner can delete rating actions.
rating.manage	The partner can create, read, update, and delete rating actions.
rating.read	The partner can read rating actions.
rating.update	The partner can update rating actions.
shortener.allow_domain_mode_proxypass	The partner can set `domain.mode` for the Domain object to `proxy_pass`.
shortener.allow_domain_secure_required	The partner can set `domain.secure` for the Domain object to `required`.
shortener.allow_link_mode_proxypass	The partner can set `link.mode` for the Link object to `proxy_pass`.
shortener.create	The partner can create Shortener objects.
shortener.delete	The partner can delete Shortener objects.
shortener.manage	The partner can create, read, update, and delete Shortener objects.
shortener.read	The partner can read Shortener objects.
shortener.update	The partner can update Shortener objects.
sms.create	The partner can create SMS objects.
sms.delete	The partner can delete SMS objects.
sms.manage	The partner can create, read, update, and delete SMS objects.
sms.read	The partner can read SMS objects.
sms.read_descendant	The partner can view SMS object detailed records for the inherited partner.
sms.update	The partner can update SMS objects.
storage.allow_container_publish_domain_update	The partner can modify the publish domain for the storage Container object.
storage.create	The partner can create Storage objects.
storage.delete	The partner can delete Storage objects.
storage.manage	The partner can create, read, update, and delete Storage objects.
storage.read	The partner can read Storage objects.
storage.update	The partner can update Storage objects.
system.create	The partner can create system actions.
system.delete	The partner can delete system actions.
system.manage	The partner can create, read, update, and delete system actions.
system.read	The partner can read system actions.
system.update	The partner can update system actions.
trunk_groups.allow_external_handlers_update	The partner can modify the `external_handlers` field of the Trunk Group object.
trunk_groups.create	The partner can create Trunk Group objects.
trunk_groups.delete	The partner can delete Trunk Group objects.
trunk_groups.manage	The partner can create, read, update, and delete Trunk Group objects.
trunk_groups.read	The partner can read Trunk Group objects.
trunk_groups.trunks.allow_trunk_allow_forward_update	The partner can modify the `allow_forward` field of the Trunk object.
trunk_groups.trunks.create	The partner can create Trunk objects.
trunk_groups.trunks.delete	The partner can delete Trunk objects.
trunk_groups.trunks.manage	The partner can create, read, update, and delete Trunk objects.
trunk_groups.trunks.read	The partner can read Trunk objects.
trunk_groups.trunks.update	The partner can update Trunk objects.
trunk_groups.update	The partner can update Trunk Group objects.
verification.create	The partner can create Verification objects.
verification.delete	The partner can delete Verification objects.
verification.manage	The partner can create, read, update, and delete Verification objects.
verification.read	The partner can read Verification objects.
verification.update	The partner can update Verification objects.

acls and parent_assigned_acls

Attribute	Data Type	Description
access_control_rules	array	The list of access control rules belonging to this access control list.
direction	string	The direction for the ACL. Values accepted in this field are: `inbound`, `outbound`, and `any`.
sms_action_false	string	The action to be executed for SMS if none of the Access Control Rules are applied. Values accepted in this field are `accept` and `reject`.
sms_action_true	string	The action to be executed for SMS if any of the Access Control Rules are applied. Values accepted in this field are `accept` and `reject`.
voice_action_false	string	The action to be executed for call if none of the Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `reject503`.
voice_action_true	string	The action to be executed for call if any of the Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `reject503`.

Create Partner

The following POST request 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"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Partner object.

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "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 new partner. When a new 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.

Note that new partners will not appear in a GET request response until the associated email address has been verified.

Method	URL
POST	/partners

Body Arguments

Data Type	Description
object	The body of the Partner object to be created. Refer to the Partner Object for a list of fields that appear in the Partner object. The parameters needed to create a new partner are: `country_code` `login` `password` `owner_email` `zip` Note that the `login` value must be unique.

Get Partner

The following GET request returns a list of partners.

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

A successful request will return a 200 response code with a serialized copy of the Partner object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "acls": [],
            "address1": null,
            "address2": null,
            "attributes": {},
            "available_scopes": [
                "partners.read",
                "partners.update",
                "partners.billing_method.manage",
                "oauth.manage",
                "oauth.manage_all_tokens",
                "oauth.allow_token_scope_update",
                "endpoints.manage",
                "trunk_groups.manage",
                "trunk_groups.trunks.manage",
                "accesscontrol.manage",
                "phonenumber.manage",
                "sms.manage",
                "push.manage",
                "calls.manage",
                "app.manage",
                "invoices.manage",
                "rating.manage",
                "lookup.dids.read",
                "verification.manage",
                "storage.manage",
                "shortener.manage",
                "countries.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
}

The request returns a list of partners. Note that email addresses will not appear in the response until they have been verified. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/partners

Get Partner by SID

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

A successful request will return a 200 response code with a serialized copy of the Partner object.

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "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 the secure ID. Note that email addresses will not appear in the response until they have been verified. This request is enabled for Field Filtering.

Method	URL
GET	/partners/{partner_sid}

Path Arguments

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

Update Partner

The following PATCH request updates a Partner object targeted by secure ID.

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'

A successful request will return a 200 response code with a serialized copy of the Partner object.

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "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"
}

A partner can be updated using PATCH and PUT requests. 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 will be updated. All other attributes and values will remain the same. The partner secure ID is passed in the query URL, and the parameters are passed in the request body. This request can be used to update the partner password, partner address, and add or remove acls and transformations.

Method	URL
PATCH	/partners/{partner_sid}
PUT	/partners/{partner_sid}

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

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

To view all fields that appear in the Partner object, see the Partner Object.

Delete Partner

The following DELETE request deletes a Partner object.

curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-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 partner. 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.

Method	URL
DELETE	/partners/{partner_sid}

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.

Attribute	Data Type	Description
address1	string	The customer address.
address2	string	The customer address second field.
cc_cid	string	The credit card CID.
cc_expiration	string	The credit card expiration date in `mmyyyy` format.
cc_number	string	The credit card number.
city	string	The customer city.
country_code	string	The partner country code.
ec_account_number	string	The electronic check account number.
ec_routing_number	string	The electronic check routing number.
first_name	string	The partner first name.
last_name	string	The partner last name.
phone	string	The partner phone number.
state	string	The customer state in two-letter abbreviation format.
type	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	string	The customer zip code.

Register Billing Method

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

A successful request will return a 200 response code with a serialized copy of the Billing Method object.

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

This request will register the billing method for a customer. Note that the cc_number value will be redacted as the last four integers in the response.

Method	URL
POST	/partners/{partner_sid}/billing_method

Path Arguments

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

Body Arguments

JSON representation of the fields and values for the billing method to be registered.

The fields needed to create a new billing method are:

cc_expiration
cc_number
country_code
first_name
last_name
phone
type
zip

To view all fields in the Billing Method object, see the Billing Method Object.

Get Billing Method by Partner SID

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

A successful request will return a 200 response 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 will return information registered for the selected partner. This request is enabled for Field Filtering.

Method	URL
GET	/partners/{partner_sid}/billing_method

Path Arguments

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

Delete Billing Method

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

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

This request will delete a billing method of the partner, targeted by secure ID. When completed, no billing method will be registered for the specified partner.

Method	URL
DELETE	/partners/{partner_sid}/billing_method

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 DIDs. DIDs can be organized into DID Groups. Refer to Browse Available DIDs 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.

Attribute	Data Type	Description
attributes	object	The DID attributes.
callback_url	string	The callback URL to receive events for SMS.
capabilities	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 inbound SMS `2` for outbound SMS `4` for voice To enable inbound SMS and voice, add `1` and `4` together to make `5`.
country_code	string	The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
did_group_sid	string	The DID group secure ID.
did_sid	string	The DID secure ID.
in_country_format	string	The DID in a national format.
international_format	string	The DID in an international format.
locality	string	The locality or city of the DID.
name	string	The DID name. The default value is `N/A`.
partner_sid	string	The secure ID of the partner associated with the DID.
phonenumber	string	The phone number for the DID in E.164 format.
price	integer	The price of the DID.
state	string	The state or province of the DID.
transformations	string	The transformations that are applied to the DID. Refer to the transformations section for more information.
trunk_group_sid	string	The secure ID of the trunk group associated with the DID.

Rent DID

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

A successful request will return a 200 response 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",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "transformations": [],
    "trunk_group_sid": null
}

This request assigns a DID to a partner.

Method	URL
POST	/phonenumber/dids

Body Arguments

JSON representation of the fields and values of the DID to be created. A valid and available phonenumber is required to rent a DID. Note that once the phone number has been rented, it must be assigned a trunk group to be usable.

To view all fields that appear in the DID object, see the DID Object.

Get DIDs

The following GET request returns rented DIDs.

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

A successful request will return a 200 response code with 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",
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "phonenumber": "15162065574",
            "price": "0.6",
            "state": "NY",
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/dids?limit=1&offset=1"
    },
    "total": 2
}

This request returns a list of DIDs that have been rented. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/dids

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.

Get DID by SID

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

A successful request will return a 200 response code with a DID object targeted by secure ID.

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

This request returns data about a DID, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/phonenumber/dids/{did_sid}

Path Arguments

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

Update DID

The following PATCH request updates a DID, targeted by the DID secure ID.

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'

A successful request will return a 200 response code with an updated DID object targeted by secure ID.

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

A DID can be updated through PATCH and PUT requests. A PATCH request requires the DID secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the DID secure ID passed in the query URL, as well as the entire DID object passed in the query body.

Method	URL
PATCH	/phonenumber/dids/{did_sid}
PUT	/phonenumber/dids/{did_sid}

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

attributes
callback_url
did_group_sid
name
transformations
trunk_group_sid

To view all fields that appear in the DID object, see the DID Object.

Delete DID

The following DELETE request deletes a DID.

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

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

This request releases a DID from a partner account. The same DID cannot be immediately rented again. To recover a released phone number, contact technical support at support@carrierx.com.

Method	URL
DELETE	/phonenumber/dids/{did_sid}

Path Arguments

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

DID Emergency Object

This section goes over the parts of the Emergency object. These fields and values make up the JSON response that gets returned when a request is successful.

To view or manage the Emergency locations, the partner must have the appropriate scopes enabled (phonenumber.emergency.manage, phonenumber.emergency.read)

Parameter	Data Type	Description
caller_name	string	The name that will appear on receiving party phones.
enabled	boolean	If this field is set to `false`, no record is stored in the central CNAM registry. Fields can still be updated when the value is `false`.
locations	array of objects	The list of locations that will be used for emergency. Refer to the table below for the description of the location object parameters.

Location Object

Parameter	Data Type	Description
address_1	string	The emergency location address line 1.
address_2	string	The emergency location address line 2.
city	string	The emergency location city.
country_code	string	The ISO 3166-1 alpha-3 code of this emergency location country.
state	string	The emergency location state in two-letter abbreviation format.
zip	string	The emergency location zip code.

Get DID Emergency

The following GET request returns DID Emergency.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Emergency object.

{
    "caller_name": "John Smith",
    "enabled": true,
    "locations": [
        {
            "address_1": "8104 E Nora Ave",
            "address_2": "",
            "city": "Spokane Valley",
            "country_code": "USA",
            "state": "WA",
            "zip": "99212"
        },
        {
            "address_1": "600 Boll Weevil Cir",
            "address_2": "",
            "city": "Enterprise",
            "country_code": "USA",
            "state": "AL",
            "zip": "36330"
        }
    ]
}

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

Method	URL
GET	/phonenumber/dids/{did_sid}/emergency

Update DID Emergency

The following PATCH request updates a DID Emergency object.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
--data-binary '{"caller_name": "J Smith"}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Emergency object.

{
    "caller_name": "J Smith",
    "enabled": true,
    "locations": [
        {
            "address_1": "8104 E Nora Ave",
            "address_2": "",
            "city": "Spokane Valley",
            "country_code": "USA",
            "state": "WA",
            "zip": "99212"
        },
        {
            "address_1": "600 Boll Weevil Cir",
            "address_2": "",
            "city": "Enterprise",
            "country_code": "USA",
            "state": "AL",
            "zip": "36330"
        }
    ]
}

DID Emergency can be updated through PATCH and PUT requests. A PATCH request requires the DID secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the DID secure ID passed in the query URL, as well as the entire DID Emergency object passed in the query body.

Method	URL
PATCH	/phonenumber/dids/{did_sid}/emergency
PUT	/phonenumber/dids/{did_sid}/emergency

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated. All fields can be updated.

To view all fields that appear in the DID Emergency object, see the DID Emergency Object.

Delete DID Emergency

The following DELETE request deletes a DID Emergency object.

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/emergency' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

This request deletes DID Emergency for a specific DID.

Method	URL
DELETE	/phonenumber/dids/{did_sid}/emergency

Path Arguments

Parameter	Data Type	Description
did_sid `required`	string	The secure ID of the DID with the Emergency that is to be deleted.

DID Line Information Object

This section goes over the parts of the Line Information object. These fields and values make up the JSON response that gets returned when a request is successful.

To enable this feature on your account, contact technical support at support@carrierx.com.

Parameter	Data Type	Description
caller_name	string	The name that will appear on receiving party phones.
class_of_service	string	The type of establishment that the service is for, either `none`, `residential`, or `business`. The default is `none`.
enabled	boolean	If this field is set to `false`, no record is stored in the central CNAM registry. Fields can still be updated when the value is `false`.
extended_business_name	string	The business name associated with the caller. This extended information is given according to the provider and phone device.
extended_first_name	string	The first name of the caller. This extended information is given according to the provider and phone device.
extended_last_name	string	The last name of the caller. This extended information is given according to the provider and phone device.
privacy	string	Either `public` or `private`. This is whether or not the caller name will be displayed. The default is `public`.
screening	integer	Determines what types of calls are accepted. Assign `0` to allow all calls, `1` to block third number (operator assisted) calls, `2` to block collect calls, and `3` to block third number (operator assisted) and collect calls. The default value is `3`.

Get DID Line Information

The following GET request returns DID line information.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Line Information object.

{
    "enabled": true,
    "class_of_service": "business",
    "screening": "allow_all",
    "privacy": "public",
    "caller_name": "John Smith",
    "extended_first_name": "John",
    "extended_last_name": "Smith",
    "extended_business_name": "J Smith Carpenter"
}

This request returns DID line information, and is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/dids/{did_sid}/line_information

Update DID Line Information

The following PATCH request updates a DID Line Information object.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
--data-binary '{"caller_name": "J Smith"}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Line Information object.

{
    "enabled": true,
    "class_of_service": "business",
    "screening": "allow_all",
    "privacy": "public",
    "caller_name": "J Smith",
    "extended_first_name": "John",
    "extended_last_name": "Smith",
    "extended_business_name": "J Smith Carpenter"
}

DID line information can be updated through PATCH and PUT requests. A PATCH request requires the DID secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the DID secure ID passed in the query URL, as well as the entire DID line information object passed in the query body.

Method	URL
PATCH	/phonenumber/dids/{did_sid}/line_information
PUT	/phonenumber/dids/{did_sid}/line_information

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated. All fields can be updated.

To view all fields that appear in the DID Line Information object, see the DID Line Information Object.

Delete DID Line Information

The following DELETE request deletes a DID line information object.

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/0493d917-e23c-41db-8067-0c986df71007/line_information' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

This request deletes DID line information for a specific DID.

Method	URL
DELETE	/phonenumber/dids/{did_sid}/line_information

Path Arguments

Parameter	Data Type	Description
did_sid `required`	string	The secure ID of the DID with the line information that is to be deleted.

DID Group Object

This section goes over the parts of the DID Group object. These fields and values make up the JSON response that gets returned when a request is successful.

The following fields appear in an items object.

Parameter	Data Type	Description
did_group_sid	string	The DID group secure ID.
name	string	The name of the DID group.
partner_sid	string	The partner secure ID.

Create DID Group

The following POST request creates a new DID Group.

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

A successful request will return a 200 response code with a serialized copy of the DID Group object.

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

This request creates a new DID group.

Method	URL
POST	/phonenumber/did_groups

Body Arguments

JSON representation of the fields and values of the DID group to be created. There are no required fields to create a DID group.

To view all fields that appear in the DID Group object, see the DID Group Object.

Get DID Groups

The following GET request returns DID Groups.

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

A successful request will return a 200 response code with a serialized copy of the DID Group object.

{
    "offset": 0,
    "limit": 1,
    "count": 1,
    "total": 2,
    "has_more": true,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/did_groups?limit=1&offset=1"
    },
    "items": [
        {
            "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "name": "N/A"
        }
    ]
}

This request returns a list of DID groups. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/did_groups

Get DID Group by SID

The following GET request returns a DID Group, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Group object.

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

This request returns a list of DID groups, targeted by secure ID.

Method	URL
GET	/phonenumber/did_groups/{did_group_sid}

Path Arguments

Parameter	Data Type	Description
did_group_sid `required`	string	The secure ID of the DID group.

Update DID Group

The following PATCH request updates a DID Group.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_did_group"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the DID Group object.

{
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "my_did_group",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

A DID Group can be updated through PATCH and PUT requests. A PATCH request requires the DID Group secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the DID Group secure ID passed in the query URL, as well as the entire DID Group object passed in the query body.

Method	URL
PATCH	/phonenumber/did_groups/{did_group_sid}
PUT	/phonenumber/did_groups/{did_group_sid}

Path Arguments

Parameter	Data Type	Description
did_group_sid `required`	string	The secure ID of the DID Group.

Body Arguments

JSON representation of the fields and values to be updated. The field that can be updated is name.

To view all fields that appear in the DID Group object, see the DID Group Object.

Delete DID Group

The following DELETE request deletes a DID Group, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This request deletes a DID group.

Method	URL
DELETE	/phonenumber/did_groups/{did_group_sid}

Path Arguments

Parameter	Data Type	Description
did_group_sid `required`	string	The secure ID of the DID group to be deleted.

Prefix Object

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

Parameter	Data Type	Description
attributes	object	The prefix attributes.
callback_url	string	The callback URL.
name	string	The prefix name. The default value is `N/A`.
partner_sid	string	The partner secure ID.
prefix	string	The prefix that will enable routing logic.
prefix_sid	string	The prefix secure ID.
transformations	array	The prefix transformations.
trunk_group_sid	string	The trunk group secure ID.

Create Prefix

The following POST request creates a prefix.

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

A successful request will return a 200 response code with a serialized copy of the Prefix object.

{
    "attributes": {},
    "callback_url": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "transformations": [],
    "trunk_group_sid": null
}

This request creates a new Prefix object.

Method	URL
POST	/phonenumber/prefixes

Body Arguments

JSON representation of the fields and values of the prefix to be created. The parameter needed to create a new prefix is prefix.

To view all fields that appear in the Prefix object, see the Prefix Object.

Get Prefixes

The following GET request returns prefixes.

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

A successful request will return a 200 response code with a serialized copy of the Prefix object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "prefix": "111111111111111",
            "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of Prefix objects. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/prefixes

Get Prefix by SID

The following GET request returns prefixes, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Prefix object.

{
    "attributes": {},
    "callback_url": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "transformations": [],
    "trunk_group_sid": null
}

This request will return the Prefix object associated with a specific prefix secure ID.

Method	URL
GET	/phonenumber/prefixes/{prefix_sid}

Path Arguments

Parameter	Data Type	Description
prefix_sid `required`	string	The prefix secure ID.

Update Prefix

The following PATCH request updates a prefix, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"main prefix"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Prefix object.

{
    "attributes": {},
    "callback_url": null,
    "name": "main prefix",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "transformations": [],
    "trunk_group_sid": null
}

A Prefix object can be modified using PATCH and PUT requests. 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 will be updated. The prefix secure ID is passed in the query URL, and the parameters and values to be updated are passed in the request body. A PUT request is used to update the entire Prefix object. The prefix secure ID is passed in the query URL, and the entire Prefix object is passed in the request body.

Method	URL
PATCH	/phonenumber/prefixes/{prefix_sid}
PUT	/phonenumber/prefixes/{prefix_sid}

Path Arguments

Parameter	Data Type	Description
prefix_sid `required`	string	The prefix secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

attributes
callback_url
name
prefix
transformations

To view all fields that appear in the Prefix object, see the Prefix Object.

Delete Prefix

The following DELETE request deletes a prefix, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This request deletes a prefix, targeted by secure ID.

Method	URL
DELETE	/phonenumber/prefixes/{prefix_sid}

Path Arguments

Parameter	Data Type	Description
prefix_sid `required`	string	The secure ID of the prefix.

Short Code Object

This section outlines the Short Code object. The fields listed in the table below will be returned in a JSON object when a successful request has been made. Contact technical support at support@carrierx.com to create a short code.

Parameter	Data Type	Description
attributes	object	The attributes of the short code.
callback_url	string	The callback URL.
country_code	string	The country of the short code.
did_group_sid	string	The DID group secure ID.
locality	string	The region of the short code.
partner_sid	string	The partner secure ID.
short_code	string	The short code.
short_code_sid	string	The short code secure ID.
state	string	The state of the short code.

Get Short Codes

The following GET request returns short codes.

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

A successful request will return a 200 response code with a serialized copy of the Short Code object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "country_code": "USA",
            "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562",
            "locality": null,
            "name": "test",
            "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417",
            "short_code": "26399",
            "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc",
            "state": "IL"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of Short Code objects. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/short_codes

Get Short Code by SID

The following GET request returns a short code, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Short Code object.

{
    "attributes": {},
    "callback_url": null,
    "country_code": "USA",
    "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562",
    "locality": null,
    "name": "test",
    "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417",
    "short_code": "26399",
    "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc",
    "state": "IL"
}

This request returns a Short Code object, targeted by secure ID. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/short_codes/{short_code_sid}

Path Arguments

Parameter	Data Type	Description
short_code_sid `required`	string	The short code secure ID.

Update Short Code

The following PATCH request updates a short code, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
--data-binary '{"name":"new shortcode name"}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Short Code object.

{
    "attributes": {},
    "callback_url": null,
    "country_code": "USA",
    "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562",
    "locality": null,
    "name": "new short code name",
    "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417",
    "short_code": "26399",
    "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc",
    "state": "IL"
}

A Short Code object can be modified using PATCH and PUT requests. 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 will be updated. The short code secure ID is passed in the query URL, and the parameters and values to be updated are passed in the request body. A PUT request is used to update the entire Short Code object. The short code secure ID is passed in the query URL, and the entire Short Code object is passed in the request body.

Method	URL
PATCH	/phonenumber/short_codes/{short_code_sid}
PUT	/phonenumber/short_codes/{short_code_sid}

Path Arguments

Parameter	Data Type	Description
short_code_sid `required`	string	The short code secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

attributes
callback_url
name

To view all fields that appear in the Short Code object, see the Short Code Object.

Delete Short Code

The following DELETE request deletes a short code.

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
-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 short code, targeted by secure ID.

Method	URL
DELETE	/phonenumber/short_codes/{short_code_sid}

Path Arguments

Parameter	Data Type	Description
short_code_sid `required`	string	The secure ID of the short code.

Browse Available DIDs

The following GET request returns available DIDs.

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

A successful request will return a 200 response code with a serialized copy of available DIDs.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "country_code": "USA",
            "did_group_sid": null,
            "did_sid": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
            "in_country_format": "(516) 206-5573",
            "international_format": "+1 516-206-5573",
            "locality": "NEW YORK",
            "name": "N/A",
            "partner_sid": null,
            "phonenumber": "15162065573",
            "price": "0.6",
            "state": "NY",
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&offset=1"
    },
    "total": null
}

This request returns a pool of rentable phone numbers. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/available_dids
GET	/dids/inventory (deprecated)

Browse Coverage

The following GET request returns data about available phone numbers.

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

A successful request will return a 200 response code with a data about available phone numbers.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "count": 81,
            "key": "IL"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/coverage?limit=1&group_by=state&offset=1"
    },
    "total": 5
}

This request returns data about available phone numbers rentable through CarrierX. Responses can also include inventory levels. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/coverage

Query Arguments

Parameter	Data Type	Description
group_by `required`	string	Which criteria the results should be grouped by. Values accepted in this field are: `country`, `state`, `locality`, `npa`, and `npa_nxx`. Note that only one value is accepted at a time.

Response Object

Attribute	Data Type	Description
count	integer	The total quantity of phone numbers for the given NPA.
key	string	The value by which the phone numbers are grouped in the response.

Get Rates

The following GET request returns phone number rates.

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

A successful request will return a 200 response code with phone number rates.

{
    "active": "yes",
    "count": 1,
    "effective_date": "2017-08-03T00:00:00.000Z",
    "has_more": false,
    "items": [
        {
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.6"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "rates_plan": {
        "name": "did_retail-2017-08-03.txt",
        "rates_plan_sid": "326d2ec0-c58c-43e2-85f3-a92d647e46ac"
    },
    "total": 1
}

This request returns monthly rental fees for a phone number matching the defined criteria. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/rates
GET	/dids/rates (deprecated)

Response Object

Attribute	Data Type	Description
country_code	string	The ISO 3166-1 alpha-3 code of this rate.
country_name	string	The country name of this rate.
prefix	string	The number prefix for the DID.
price	integer	The price for this rate.

Look Up Rates by Phone Number

The following GET request returns rates for a specific phone number.

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

A successful request will return a 200 response code with phone number rates.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.6"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns rates for a specified phone number. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/phonenumber/rates/{phonenumber}

Path Arguments

Parameter	Data Type	Description
phonenumber `required`	string	The phone number.

Response Object

Attribute	Data Type	Description
country_code	string	The ISO 3166-1 alpha-3 code of this rate.
country_name	string	The country name of this rate.
prefix	string	The number prefix for this DID.
price	integer	The price for this rate.

Prerouting

Prerouting is used to troubleshoot the issues that occur with the locations or DIDs. It uses the wide abilities of the Kamailio SIP server for debugging of the problems. It takes the specified phone number and directs all the traffic to or from this number via the Kamailio SIP server proxy allowing to view additional data about the calls.

Prerouting Object

This section outlines the Prerouting 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
date_max_ttl_changed	string	The date and time when the `maximum_ttl` field was last changed.
description	string	The description of the prerouting.
maximum_ttl	integer	The maximum lifetime of the prerouting in minutes. The `-1` value sets this value to `unlimited`.
name	string	The name of the prerouting.
phonenumber	string	The phone number the prerouting will be applied to.
pool	integer	The Kamailio pool prefix. The currently accepted value is `100`.
prerouting_sid	string	The prerouting secure ID.
type	string	The type of the search that will be used to look for the phone number. Values accepted in this field are: `number_dst` for the destination phone number. `number_dst_last10` for the last ten digits of the destination phone number. `number_src` for the source phone number. `number_src_last10` for the last ten digits of the source phone number.

Create Prerouting

The following POST request creates a prerouting.

curl -X POST \
'https://api.carrierx.com/core/v2/system/kamailio_preroutings' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber": "61361361330", "type": "number_src", "pool": 100, "name": "Debug prerouting"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Prerouting object.

{
    "date_max_ttl_changed": "2020-07-06T10:09:16.000Z",
    "description": "",
    "maximum_ttl": -1,
    "name": "Debug prerouting",
    "phonenumber": "61361361330",
    "pool": 100,
    "prerouting_sid": "61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82",
    "type": "number_src"
}

The request will create a new prerouting for the specified phone number.

Method	URL
POST	/system/kamailio_preroutings

Body Arguments

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

Required fields to create a new prerouting are:

phonenumber
pool
type

To view all fields that appear in the Prerouting object, see the Prerouting object.

Get Preroutings

The following GET request returns preroutings.

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

A successful request will return a 200 response code with a serialized copy of the Prerouting objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "date_max_ttl_changed": "2020-07-06T10:09:16.000Z",
            "description": "",
            "maximum_ttl": -1,
            "name": "Debug prerouting",
            "phonenumber": "61361361330",
            "pool": 100,
            "prerouting_sid": "61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82",
            "type": "number_src"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of preroutings used for the partner. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/system/kamailio_preroutings

Get Prerouting by SID

The following GET request returns a prerouting, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/system/kamailio_preroutings/61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Prerouting object.

{
    "date_max_ttl_changed": "2020-07-06T10:09:16.000Z",
    "description": "",
    "maximum_ttl": -1,
    "name": "Debug prerouting",
    "phonenumber": "61361361330",
    "pool": 100,
    "prerouting_sid": "61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82",
    "type": "number_src"
}

This request returns data about a prerouting, targeted by secure ID. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/system/kamailio_preroutings/{prerouting_sid}

Path Arguments

Parameter	Data Type	Description
prerouting_sid `required`	string	The prerouting secure ID.

Update Prerouting

The following PATCH request updates a prerouting, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/system/kamailio_preroutings/61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "another name"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Prerouting object.

{
    "date_max_ttl_changed": "2020-07-06T10:09:16.000Z",
    "description": "",
    "maximum_ttl": -1,
    "name": "another name",
    "phonenumber": "61361361330",
    "pool": 100,
    "prerouting_sid": "61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82",
    "type": "number_src"
}

A Prerouting object can be modified using PATCH and PUT requests.

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 will be updated. The prerouting secure ID is passed in the query URL, and the values to be updated are passed in the request body.
A PUT request can be used to update an entire Prerouting object. The prerouting secure ID is passed in the query URL, and the entire Prerouting object is passed in the request body.

Method	URL
PATCH	/system/kamailio_preroutings/{prerouting_sid}
PUT	/system/kamailio_preroutings/{prerouting_sid}

Path Arguments

Parameter	Data Type	Description
prerouting_sid `required`	string	The prerouting secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

description
maximum_ttl
name
phonenumber
pool
type

To view all fields that appear in the Prerouting object, see the Prerouting object.

Delete Prerouting

The following DELETE request deletes a prerouting, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/system/kamailio_preroutings/61c2e73f-2f6b-4cb5-8434-2cdc61a8bd82' \
-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 prerouting, targeted by secure ID.

Method	URL
DELETE	/system/kamailio_preroutings/{prerouting_sid}

Path Arguments

Parameter	Data Type	Description
prerouting_sid `required`	string	The secure ID of the prerouting.

Push

Push notifications are the operating system-supported messages that are sent to a mobile device. To send out a push notification, an Application object must be created and at least one Device object must be associated with it. Messages are sent from applications to devices.

Application Object

This section outlines the Application 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
apns_id	string	The Apple Push Messaging Application ID.
apns_p12	string	The Apple Push Notification P12 certificate, encoded to Base64.
apns_p12_password	string	The passphrase of the Apple Push Notification P12 certificate.
application_sid	string	The application secure ID.
google_id	string	The Google Push Messaging Application ID.
google_key	string	The Google Push Messaging authentication key.
name	string	The name of the application.
partner_sid	string	The partner secure ID.

Create Application to Send Push Notifications

The following POST request creates an application.

curl -X POST \
'https://api.carrierx.com/core/v2/push/applications' \
-H 'Content-Type: application/json' \
--data-binary '{"google_id":"", "google_key":"", "apns_id":"", "apns_p12":"", "apns_p12_password":""}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Application object.

{
    "name": "N/A",
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "google_id": "",
    "google_key": "",
    "apns_id": "",
    "apns_p12": null,
    "apns_p12_password": null
}

This request will add a new application for sending out push notifications.

Method	URL
POST	/push/applications

Body Arguments

JSON representation of the Application object to be created. An empty object can be passed.

To view all fields that appear in the Application object, see the Application Object.

Get Applications

The following GET request returns applications.

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

A successful request will return a 200 response code with a serialized copy of the Application object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "apns_id": null,
            "apns_p12": null,
            "apns_p12_password": null,
            "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
            "google_id": null,
            "google_key": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of applications used for sending push notifications to devices. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/push/applications

Get Application by SID

The following GET request returns an application, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Application object.

{
    "apns_id": null,
    "apns_p12": null,
    "apns_p12_password": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": null,
    "google_key": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

This request returns data about an application, targeted by secure ID. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/push/applications/{application_sid}

Path Arguments

Parameter	Data Type	Description
application_sid `required`	string	The application secure ID.

Update Application

The following PATCH request updates an application, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "another name"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Application object.

{
    "apns_id": null,
    "apns_p12": null,
    "apns_p12_password": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": null,
    "google_key": null,
    "name": "another name",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

An Application object can be modified using PATCH and PUT requests. 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 will be updated. The prefix secure ID is passed in the query URL, and the values to be updated are passed in the request body. A PUT request can be used to update an entire Application object. The application secure ID is passed in the query URL, and the entire Application object is passed in the request body.

Method	URL
PATCH	/push/applications/{application_sid}
PUT	/push/applications/{application_sid}

Path Arguments

Parameter	Data Type	Description
application_sid `required`	string	The application secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

apns_id
apns_p12_password
apns_p12
google_id
google_key
name

To view all fields that appear in the Application object, see the Application Object.

Delete Application

The following DELETE request deletes an application, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-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 application, targeted by secure ID. Note that deleting an application will remove the device where it has been installed.

Method	URL
DELETE	/push/applications/{application_sid}

Path Arguments

Parameter	Data Type	Description
application_sid `required`	string	The secure ID of the application.

Device Object

This section goes over the parts of the Device object. This is the JSON response that gets returned when a request is successful.

Attribute	Data Type	Description
application_sid	string	The application secure ID installed on the device.
application_version	string	The version of the application on the device.
device_sid	string	The device secure ID.
environment	string	The environment to be used to send push notifications, applicable to Apple Push Notification. Values accepted in this field are `development` and `production`.
os_version	string	The device operating system version.
partner_sid	string	The partner secure ID.
token	string	The Push Notification identifying token from Google or Apple.
type	string	The type of the device. Values accepted in this field are `inbound` and `android`.

Create Device to Send Push Notifications

THe following POST request creates a device.

curl -X POST \
'https://api.carrierx.com/core/v2/push/devices' \
-H 'Content-Type: application/json' \
--data-binary '{"application_sid":"b3edc875-f73c-4c48-895a-8697b92b8d07", "type":"ios", "token":"1111", "os_version":"", "application_version":""}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Device object.

{
    "device_sid": "56d485ae-0693-421a-91eb-6b02b152573a",
    "application_sid": "b3edc875-f73c-4c48-895a-8697b92b8d07",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "type": "ios",
    "environment": "production",
    "os_version": "",
    "application_version": "",
    "token": "1111"
}

This request creates a new application for sending out push notifications.

Method	URL
POST	/push/devices

Body Arguments

JSON representation of the fields and values of the Device object to be created. Note that the environment value will be set to production unless otherwise specified.

Required fields to create a new device are:

application_sid
token
type

To view all fields that appear in the Device object, see the Device Object.

Get Devices

The following GET request returns devices.

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

A successful request will return a 200 response code with a serialized copy of the Device object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "application_sid": "b3edc875-f73c-4c48-895a-8697b92b8d07",
            "application_version": null,
            "device_sid": "56d485ae-0693-421a-91eb-6b02b152573a",
            "environment": "production",
            "os_version": null,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "token": "1111",
            "type": "ios"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of applications used for push notifications. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/push/devices

Get Device by SID

The following GET request returns a device, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/push/devices/56d485ae-0693-421a-91eb-6b02b152573a' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Device object.

{
    "application_sid": "b3edc875-f73c-4c48-895a-8697b92b8d07",
    "application_version": null,
    "device_sid": "56d485ae-0693-421a-91eb-6b02b152573a",
    "environment": "production",
    "os_version": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "token": "1111",
    "type": "ios"
}

This request returns data about a device, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/push/devices/{device_sid}

Path Arguments

Parameter	Data Type	Description
device_sid `required`	string	The device secure ID.

Update Device

The following PATCH request updates a device.

curl -X PATCH \
'https://api.carrierx.com/core/v2/push/devices/56d485ae-0693-421a-91eb-6b02b152573a' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"android"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Device object.

{
    "application_sid": "b3edc875-f73c-4c48-895a-8697b92b8d07",
    "application_version": null,
    "device_sid": "56d485ae-0693-421a-91eb-6b02b152573a",
    "environment": "production",
    "os_version": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "token": "1111",
    "type": "android"
}

Devices can be updated using a PATCH or PUT request. A PATCH request requires passing the device secure ID in the query URL, and the parameter to be updated through the request body. A PUT request requires passing the device secure ID in the query, and passing the entire Device object in the request body.

Method	URL
PATCH	/push/devices/{device_sid}
PUT	/push/devices/{device_sid}

Path Arguments

Parameter	Data Type	Description
device_sid `required`	string	The device secure ID.

Body Arguments

JSON representation of the fields to be updated. Fields that can be changed are token and type.

To view all fields that appear in the Device object, see the Device Object.

Delete Device

The following DELETE request deletes a device, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/push/devices/56d485ae-0693-421a-91eb-6b02b152573a' \
-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 device, targeted by secure ID.

Method	URL
DELETE	/push/devices/{device_sid}

Path Arguments

Parameter	Data Type	Description
device_sid `required`	integer	The secure ID of the device to be removed.

Notification Object

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

Parameter	Data Type	Description
android_click_action	string	The action when a user clicks on the notification.
android_icon	string	The notification icon.
android_sound	string	The sound file that is included in an app that will play instead of the default device notification sound.
android_tag	string	Indicates whether each notification message results in a new entry on the notification center on Android.
body	string	The notification body text.
collapseKey	string	Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.
ios_badge	string	The badge on the client app home icon.
ios_category	string	The category APS payload.
ios_collapse_id	string	Enables `apns-collapse-id` header key that allows to display only the last message of a group of messages with the same `collapseKey` value for iOS devices.
ios_mutable_content	integer	The mutable-content APS payload.
ios_sound	string	The sound file that is included in an app that will play instead of the default device notification sound.
notification_sid	string	The notification secure ID.
partner_sid	string	The secure ID of the partner associated with the message.
priority	string	The delivery priority for the notification. Values accepted in this field are: `very_low`, `low`, `normal`, `high`, and `very_high`.
recipients	array	The list of devices secure IDs.
title	string	The notification title.
ttl	integer	The time to live in seconds for the notification.

Send Notification

The following POST request sends a notification.

curl -X POST \
'https://api.carrierx.com/core/v2/push/notifications'
-H 'Content-Type: application/json' \
--data-binary '{"title": "Notification for two recipients", "body": "MEETING_PROPOSAL_DISPATCHED", "ttl": 5, "priority": "normal", "recipients": ["901dd79e-ff4f-4ff3-9b48-c095dfb4fcef", "16e64699-3064-463b-8dc7-96783c08a3d9"]}'' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with data about the notification.

{
  "success": 2,
  "failure": 0,
  "results": {
      "16e64699-3064-463b-8dc7-96783c08a3d9": "0:1479905075982486%32e5bf16f9fd7ecd",
      "901dd79e-ff4f-4ff3-9b48-c095dfb4fcef": "success"
  }
}

This request will send a push notification to one or more devices. Recipients of the push notifications are added to the recipients array.

Method	URL
POST	/push/notifications

Body Arguments

JSON representation of the fields and values of the Notification object to be created. The only field required to create a new Device object is recipients.

To view all fields that appear in the Notification object, see the Notification Object.

Routing

The Routing API allows partners to view routing locations.

A routing location represents one of the locations where CarrierX runs a SIP switch. The location may provide information about where a call was processed, or be used to configure specific routing within a location.

Routing Location Object

This section outlines the Routing Location 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
A id	integer	The location internal ID, which is assigned automatically and cannot be changed. Can be viewed using the administrator API only.
A internal_name	string	The location internal name. Available for the administrator API only.
location_sid	string	The location secure ID.
name	string	The location name.

Get Routing Locations

The following GET request returns a list of routing locations.

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

A successful request will return a 200 response code with a list of the available routing locations.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "location_sid": "us-2",
            "name": "test",
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of the available routing locations. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/routing/locations
A GET	/admin/routing/locations

Get Routing Location by SID

The following GET request returns a routing location, targeted by secure ID.

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

A successful request will return a 200 response code with a serialized copy of the Routing Location object.

{
    "location_sid": "us-2",
    "name": "test",
}

This request returns a routing location, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/routing/locations/{location_sid}
A GET	/admin/routing/locations/{location_sid}

Path Arguments

Parameter	Data Type	Description
location_sid `required`	string	The location secure ID.

Update Routing Location

The following PATCH request updates a routing location, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/admin/routing/locations/us-2'
-H 'Content-Type: application/json' \
--data-binary '{"name": "updated name", "internal_name":"new internal name"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Routing Location object.

{
    "id": 24,
    "internal_name": "new internal name"
    "location_sid": "us-2",
    "name": "updated name",
}

Routing locations can be updated using a PATCH or PUT request. A PATCH request requires passing the routing location secure ID through the query URL, and the values to be updated through the request body. A PUT request requires passing the routing location secure ID through the query URL, and passing the entire Routing Location object through the request body.

Method	URL
PATCH	/admin/routing/locations/{location_sid}
PUT	/admin/routing/locations/{location_sid}

Path Arguments

Parameter	Data Type	Description
location_sid `required`	string	The location secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

internal_name
name

Delete Routing Location

The following DELETE request deletes a routing location.

curl -X DELETE \
'https://api.carrierx.com/core/v2/admin/routing/locations/us-2'
-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 routing location, targeted by secure ID.

Method	URL
DELETE	/admin/routing/locations/{location_sid}

Path Arguments

Parameter	Data Type	Description
location_sid `required`	string	The location secure ID.

Shortener

The Shortener API takes URLs and creates shortened versions of those URLs. Once created and configured in the proper DNS records, the links are usable. A Domain object is created first, followed by a Link object.

Domain Object

This section outlines the Domain 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
domain_name	string	The unique domain name.
domain_sid	string	The domain secure ID.
expired_mode	string	Determines whether to redirect or serve page contents directly if the link is expired. Values accepted in this field are: `proxy_pass`, `redirect_permanent`, and `redirect_temporary`.
expired_page	string	The content to serve when a link is expired.
expired_status_code	integer	The status code to be returned if the `expired_mode` value is `proxy_pass`. Values accepted in this field are: `2xx`, `4xx`, and `5xx`.
minimum_length	integer	The shortest link that the system will create.
not_found_mode	string	Determines whether to redirect or serve page contents directly if the link is not found. Values accepted in this field are: `proxy_pass`, `redirect_permanent`, and `redirect_temporary`.
not_found_page	string	The content to serve when a link is not found.
not_found_status_code	integer	The status code to be returned if the `not_found_mode` value is `proxy_pass`. Values accepted in this field are: `2xx`, `4xx`, and `5xx`.
partner_sid	string	The secure ID of the partner associated with the domain.
scope	string	Determines who can create a link using the domain_sid . Values accepted in this field are: `self`, `children`, and `public`.
secure	string	Determines whether links returned should be prefixed with `https`. Values accepted in this field are: `disabled`, `optional`, and `required`. The default value for this field is `disabled`.
suffix_pattern	string	The RegExp of suffixes allowed for partial links by the HTTP server. For example, `.(.mp3\|mp4)` will allow file names ending in `.mp3` or `.mp4`. By default, the server will not allow suffixes.

Create Domain

The following POST request creates a domain.

curl -X POST \
'https://api.carrierx.com/core/v2/shortener/domains' \
-H "Content-Type: application/json" \
--data-binary '{"domain_name":"newdomain.com"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Domain object.

{
    "domain_name": "newdomain.com",
    "domain_sid": "a0625551-63de-428e-889d-2d467b4e77a3",
    "expired_mode": "redirect_temporary",
    "expired_page": null,
    "expired_status_code": null,
    "minimum_length": 6,
    "not_found_mode": "redirect_temporary",
    "not_found_page": null,
    "not_found_status_code": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "scope": "children",
    "secure": "disabled",
    "suffix_pattern": null
}

This request creates a new Domain object.

Method	URL
POST	/shortener/domains

Body Arguments

JSON representation of the fields and values of the Domain object to be created. The only field required to create a domain is domain_name.

To view all fields that appear in the Domain object, see the Domain Object.

Get Domains

The following GET request returns domains.

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

A successful request will return a 200 response code with a serialized copy of the Domain object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "domain_name": "newdomain.com",
            "domain_sid": "a0625551-63de-428e-889d-2d467b4e77a3",
            "expired_mode": "redirect_temporary",
            "expired_page": null,
            "expired_status_code": null,
            "minimum_length": 6,
            "not_found_mode": "redirect_temporary",
            "not_found_page": null,
            "not_found_status_code": null,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "scope": "children",
            "secure": "disabled",
            "suffix_pattern": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of existing domains for the currently logged-in partner. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/shortener/domains

Get Domain by SID

The following GET request returns a domain, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Domain object.

{
    "domain_name": "newdomain.com",
    "domain_sid": "a0625551-63de-428e-889d-2d467b4e77a3",
    "expired_mode": "redirect_temporary",
    "expired_page": null,
    "expired_status_code": null,
    "minimum_length": 6,
    "not_found_mode": "redirect_temporary",
    "not_found_page": null,
    "not_found_status_code": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "scope": "children",
    "secure": "disabled",
    "suffix_pattern": null
}

This request fetches information for the specified Domain object, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/shortener/domains/{domain_sid}

Path Arguments

Parameter	Data Type	Description
domain_sid `required`	string	The domain secure ID.

Update Domain

The following PATCH request updates a domain, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-H 'Content-Type: application/json' \
--data-binary '{"domain_name":"mywebsite.com"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Domain object.

{
    "domain_name": "mywebsite.com",
    "domain_sid": "a0625551-63de-428e-889d-2d467b4e77a3",
    "expired_mode": "redirect_temporary",
    "expired_page": null,
    "expired_status_code": null,
    "minimum_length": 6,
    "not_found_mode": "redirect_temporary",
    "not_found_page": null,
    "not_found_status_code": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "scope": "children",
    "secure": "disabled",
    "suffix_pattern": null
}

A domain can be updated through PATCH and PUT requests. A PATCH request requires the domain secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the domain secure ID passed in the query URL, as well as the entire Domain object passed in the query body.

Method	URL
PATCH	/shortener/domains/{domain_sid}
PUT	/shortener/domains/{domain_sid}

Path Arguments

Parameter	Data Type	Description
domain_sid `required`	string	The domain secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

domain_name
expired_mode
expired_page
expired_status_code
minimum_length
not_found_mode
not_found_page
not_found_status_code
scope
secure
suffix_pattern

To view all fields that appear in the Domain object, see the Domain Object.

Delete Domain

The following DELETE request deletes a domain, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-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 domain, targeted by secure ID.

Method	URL
DELETE	/shortener/domains/{domain_sid}

Path Arguments

Parameter	Data Type	Description
domain_sid `required`	string	The secure ID of the domain.

Link Object

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

Attribute	Data Type	Description
date_accessed	string	The date when the link was accessed.
date_created	string	The date when the link was created.
destination_url	string	The site where the user will be sent.
domain_sid	string	The domain secure ID.
hits	integer	The number of times that the link has been hit.
link_sid	string	The link secure ID.
maximum_ttl	integer	The link lifetime in seconds. Entering the value `-1` means that the link will not expire.
mode	string	The mode of the link. Values accepted in this field are `redirect_temporary` and `redirect_permanent`.
partner_sid	string	The partner secure ID.
short_name	string	The short portion of the URL. If there is no value in this field, it will be automatically generated. This value is unique to `domain_sid`.
url	string	The URL to get access to `destination_url`. This field value is generated automatically.

Create Link

The following POST request creates a link.

curl -X POST \
'https://api.carrierx.com/core/v2/shortener/links?reuse=true' \
-H "Content-Type: application/json" \
--data-binary '{"domain_sid":"330a8a83-d4bb-4f39-ae54-c59c8d87cd44", "destination_url":"http://destinationurl.com", "maximum_ttl":"-1"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Link object.

{
    "date_accessed": null,
    "date_created": "2019-01-18T19:26:02.553Z",
    "destination_url": "http://destinationurl.com",
    "domain_sid": "330a8a83-d4bb-4f39-ae54-c59c8d87cd44",
    "hits": 0,
    "link_sid": "a533f53a-7e6f-4822-be3c-3767924ee2a9",
    "maximum_ttl": -1,
    "mode": "redirect_temporary",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "short_name": "eOtEtO",
    "url": "http://newdomain.com/eOtEtO"
}

This request creates a new link.

Method	URL
POST	/shortener/links

Query Arguments

Parameter	Data Type	Description
reuse	boolean	If set to `true`, the previously created existing link will be used (i.e., no new short link will be created) to the same `destination_url` and with the same `domain_sid`. If no existing link with the same `destination_url` and `domain_sid` can be found, the new one will be created. The default value is `false`.

Body Arguments

Data Type	Description
object	The body of the object to be created. Refer to the Link Object for a list of all fields that appear in the Link object. Fields required to create a link are `domain_sid` and `destination_url`.

Get Links

The following GET request returns links.

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

A successful request will return a 200 response code with a serialized copy of the Link object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "date_accessed": null,
            "date_created": "2019-01-18T19:26:02.000Z",
            "destination_url": "http://destinationurl.com",
            "domain_sid": "330a8a83-d4bb-4f39-ae54-c59c8d87cd44",
            "hits": 0,
            "link_sid": "a533f53a-7e6f-4822-be3c-3767924ee2a9",
            "maximum_ttl": -1,
            "mode": "redirect_temporary",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "short_name": "eOtEtO",
            "url": "http://newdomain.com/eOtEtO"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of existing links for the currently logged in partner. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/shortener/links

Get Link by SID

The following GET request returns a link, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Link object.

{
    "date_accessed": null,
    "date_created": "2019-01-18T19:26:02.000Z",
    "destination_url": "http://destinationurl.com",
    "domain_sid": "330a8a83-d4bb-4f39-ae54-c59c8d87cd44",
    "hits": 0,
    "link_sid": "a533f53a-7e6f-4822-be3c-3767924ee2a9",
    "maximum_ttl": -1,
    "mode": "redirect_temporary",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "short_name": "eOtEtO",
    "url": "http://newdomain.com/eOtEtO"
}

This request returns information for a Link object. This request is enabled for Field Filtering.

Method	URL
GET	/shortener/links/{link_sid}

Path Arguments

Parameter	Data Type	Description
link_sid `required`	string	The link secure ID.

Update Link

The following PATCH request updates a link.

curl -X PATCH \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
-H 'Content-Type: application/json' \
--data-binary '{"mode":"redirect_permanent"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Link object.

{
    "date_accessed": null,
    "date_created": "2019-01-18T19:26:02.000Z",
    "destination_url": "http://destinationurl.com",
    "domain_sid": "330a8a83-d4bb-4f39-ae54-c59c8d87cd44",
    "hits": 0,
    "link_sid": "a533f53a-7e6f-4822-be3c-3767924ee2a9",
    "maximum_ttl": -1,
    "mode": "redirect_permanent",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "short_name": "eOtEtO",
    "url": "http://newdomain.com/eOtEtO"
}

A link can be updated using PATCH and PUT requests. 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 will be updated. The link secure ID is passed in the query URL, and the parameters are passed in the request body. A PUT request can also be used to update a Link object. The link secure ID is passed in the query URL, and the entire Link object is passed in the request object.

Method	URL
PATCH	/shortener/links/{link_sid}
PUT	/shortener/links/{link_sid}

Path Arguments

Parameter	Data Type	Description
link_sid `required`	string	The link secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

destination_url
maximum_ttl
mode

To view all fields that appear in the Link object, see the Link Object.

Delete Link

The following DELETE request deletes a link, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
-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 link, targeted by secure ID.

Method	URL
DELETE	/shortener/links/{link_sid}

Path Arguments

Parameter	Data Type	Description
link_sid `required`	string	The link secure ID.

SMS

Text (SMS) and multimedia (MMS) messages can be sent from rented DIDs. Messages can be queued and sent out successively.

SMS Object

This section outlines the SMS object. SMS object is used for both SMS and MMS. 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
date_created	string	The date when the message was created.
date_status_changed	string	The date when the message status last changed.
direction	string	The direction of the message. Values accepted in this field are `inbound` for incoming messages and `outbound` for outgoing messages.
from_did	string	The phone number that the message will be from, in E.164 format.
mcc	integer	The mobile country code.
media_urls	array	The list of URLs for media resources, if `type` of message is set to `mms`.
message	string	The message body.
message_segments	integer	The quantity of 160-symbols segments of a message.
message_sid	string	The message secure ID.
mnc	integer	The mobile network code.
partner_sid	string	The secure ID of the partner this message belongs to.
price	string	The price in US dollars determined for the message to be delivered.
status	string	The status of the message. Values accepted in this field are: `created` `delivered` `failed` `internal_error` `queued` `received` `receiving` `sending` `sent` `timed_out` `undelivered`
to_did	string	The phone number that the message will be delivered to, in E.164 format.
type	string	The type of message. Values accepted in this field are `mms` and `sms`. The default value is `sms` if the `media_urls` array is empty, and `mms` if the `media_urls` array contains items.

Send SMS Message

The following POST request sends an SMS message.

curl -X POST \
'https://api.carrierx.com/core/v2/sms/messages' \
-H 'Content-Type: application/json' \
--data-binary '{"from_did":"15162065575", "to_did":"15162065574", "message":"This is a test message"}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS object.

{
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": null,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": null,
    "status": "queued",
    "to_did": "15162065574",
    "type": "sms"
}

This request will send a message from a rented DID.

Method	URL
POST	/sms/messages

Body Arguments

Data Type	Description
object	The body of the message to be sent. Refer to the SMS Object for a list of all fields that appear in the SMS object. Fields required to send a message are: `from_did` `media_urls` (only required for the `mms` message `type`) `message` `to-did`

Get SMS Messages

The following GET request returns messages.

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

A successful request will return a 200 response code with a serialized copy of the SMS object.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_created": "2019-01-18T21:01:13.415Z",
            "date_status_changed": "2019-01-18T10:01:00.000Z",
            "direction": "outbound",
            "from_did": "15162065575",
            "mcc": 0,
            "media_urls": [],
            "message": "This is a test message",
            "message_segments": 1,
            "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
            "mnc": 0,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "price": "0.01",
            "status": "delivered",
            "to_did": "15162065574",
            "type": "sms"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/sms/messages?limit=1&offset=1"
    },
    "total": null
}

This request returns a list of inbound and outbound messages. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/sms/messages

Get SMS Message by SID

The following GET request returns a message, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/messages/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS object.

{
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": "2019-01-18T10:01:00.000Z",
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": 0,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": 0,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": "0.01",
    "status": "delivered",
    "to_did": "15162065574",
    "type": "sms"
}

This request returns data about a message using the message secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/sms/messages/{message_sid}

Path Arguments

Parameter	Data Type	Description
message_sid `required`	string	The message secure ID.

SMS Detail Records Object

This section outlines the SMS Detail Records object. It displays detailed information for both sent and received SMS and MMS messages. 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
date_insert	string	Date when the detail record was inserted to the database.
date_sent	string	Date when the message was actually sent.
date_start	string	Date and time of the message creation.
date_stop	string	Date and time of the message delivering (with any status).
delay_sent	integer	Delay between when the request is received and the message is actually sent measured in seconds.
direction	string	The direction of the message. Values accepted in this field are `inbound` for incoming messages and `outbound` for outgoing messages.
dr_sid	string	Secure ID of the message detail record.
mcc	integer	The mobile country code.
media_urls	array	The list of URLs for media resources, if `type` of message is set to `mms`.
message	string	The message body.
message_segments	integer	The quantity of 160-symbols segments of a message.
mnc	integer	The mobile network code.
number_billing	string	The subscriber number in E.164 format. It will coincide with the `number_dst` in case of the `inbound` direction, or with the `number_src` in case of `outbound` direction.
number_dst	string	The destination number in E.164 format.
number_external	string	The non-subscriber number in E.164 format. It will coincide with the `number_src` in case of the `inbound` direction, or with the `number_dst` in case of `outbound` direction.
number_src	string	The source number in E.164 format.
partner_sid	string	The secure ID of the partner this message belongs to.
price	number	The price in US dollars determined for the message to be delivered.
provider	string	Provider that is used to send the message.
status	string	The status of the message. Values accepted in this field are: `created` `delivered` `failed` `internal_error` `queued` `received` `receiving` `sending` `sent` `timed_out` `undelivered`
type	string	The type of message. Values accepted in this field are `mms` and `sms`.
version	integer	The version of the detail record as it comes from the resource.

Get SMS Message Detail Records

The following GET request returns message detail records.

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

A successful request will return a 200 response code with a serialized copy of the SMS Detail Records object.

{
    "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": [
                "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
            ],
            "message": null,
            "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",
            "status": "sent",
            "type": "mms",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/sms/message_drs?limit=1&offset=1"
    },
    "total": null
}

This request returns a list of inbound and outbound messages with their detailed information. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/sms/message_drs

Get SMS Message Detail Records by SID

The following GET request returns a message detail record, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs/92cd9154-2f53-4e62-8b4e-8ff6e4849d16' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS Detail Records object.

{
    "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": [
        "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
    ],
    "message": null,
    "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",
    "status": "sent",
    "type": "mms",
    "version": null
}

This request returns the detailed data about an SMS/MMS message using the message detail record secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/sms/message_drs/{dr_sid}

Path Arguments

Parameter	Data Type	Description
dr_sid `required`	string	The message detail record secure ID.

SMS Provider Object

This section outlines the SMS Provider object. It is used to define the routing of the SMS messages, which follows the below logic.

First, CarrierX searches the NPA database for the number_dst value of the SMS Detail Records object to see if the destination number is US-based. If it is US-based, the message routing will be made using the provider.usa preference, otherwise, the lookup in the HLR database will be performed.

If the destination number is not US-based and message.mcc value is equal to the provider.mcc value, the message routing will be made using the provider.domestic preference, otherwise, the message will be routed using the provider.international preference.

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
domestic	string	The preference used for the message routing, if the destination number is not US-based and the message `mcc` value is equal to the provider `mcc` value. Values accepted in this field are: `self` for sending the message to queue corresponding to the provider. `external` for using the normal international prefix routing table.
international	string	The preference used for the message routing, if neither the destination number is US-based, nor the message `mcc` value is equal to the provider `mcc` value. Values accepted in this field are: `self` for sending the message to queue corresponding to the provider. `external` for using the normal international prefix routing table.
mcc	integer	The mobile country code.
name	string	The SMS provider name.
provider_sid	string	The SMS provider secure ID.
route_name	string	The name of the routing accociated with the message provider.
usa	string	The preference used for the message routing, if the destination number is US-based. Values accepted in this field are: `self` for sending the message to queue corresponding to the provider. `external` for using the normal international prefix routing table.

Create SMS Provider

The following POST request creates an SMS provider.

curl -X POST \
'https://api.carrierx.com/core/v2/admin/sms/providers' \
-H 'Content-Type: application/json' \
--data-binary '{ "name": "Inteliquent", "route_name": "inteliquent", "mcc": "310", "usa": "self", "domestic":"self", "international":"external" }' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS Provider object.

{
  "domestic": "self",
  "international": "external",
  "mcc": 310,
  "name": "Inteliquent",
  "provider_sid": "36e82093-21f7-487f-b8c0-c919fcf56a86",
  "route_name": "inteliquent",
  "usa": "self"
}

Method	URL
POST	/admin/sms/providers

Body Arguments

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

Required fields to create a provider are:

domestic
international
mcc
route_name
usa

To view all fields that appear in the SMS Provider object, see the SMS Provider object.

Get SMS Providers

The following GET request returns SMS providers.

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

A successful request will return a 200 response code with a serialized copy of the SMS Provider object.

{
  "count": 1,
  "has_more": true,
  "items": [
    {
      "domestic": "self",
      "international": "external",
      "mcc": 310,
      "name": "Tyntec",
      "provider_sid": "3188161b-d669-4eaf-bd59-c3b2d34c6f5f",
      "route_name": "tyntec",
      "usa": "self"
    }
  ],
  "limit": 1,
  "offset": 0,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/admin/sms/providers?limit=1&offset=1"
  },
  "total": null
}

This request returns a list of SMS providers. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/admin/sms/providers

Get SMS Provider by SID

The following GET request returns an SMS provider, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/admin/sms/providers/36e82093-21f7-487f-b8c0-c919fcf56a86' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS Provider object.

{
  "domestic": "self",
  "international": "external",
  "mcc": 310,
  "name": "Inteliquent",
  "provider_sid": "36e82093-21f7-487f-b8c0-c919fcf56a86",
  "route_name": "inteliquent",
  "usa": "self"
}

This request returns the SMS provider using the provider secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/admin/sms/providers/{provider_sid}

Path Arguments

Parameter	Data Type	Description
provider_sid `required`	string	The SMS provider secure ID.

Update SMS Provider

The following PATCH request updates an SMS provider, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/admin/sms/providers/36e82093-21f7-487f-b8c0-c919fcf56a86' \
-H 'Content-Type: application/json' \
--data-binary '{ "name": "Inteliquent updated" }' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the SMS Provider object.

{
  "domestic": "self",
  "international": "external",
  "mcc": 310,
  "name": "Inteliquent updated",
  "provider_sid": "36e82093-21f7-487f-b8c0-c919fcf56a86",
  "route_name": "inteliquent",
  "usa": "self"
}

SMS Providers can be updated using a PATCH or PUT request.

A PATCH request requires passing the SMS provider secure ID through the query URL, and the values to be updated through the request body.
A PUT request requires passing the SMS provider secure ID through the query URL, and passing the entire SMS Provider object through the request body.

Method	URL
PATCH	/admin/sms/providers/{provider_sid}
PUT	/admin/sms/providers/{provider_sid}

Path Arguments

Parameter	Data Type	Description
provider_sid `required`	string	The SMS provider secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

domestic
international
mcc
route_name
usa

To view all fields that appear in the SMS Provider object, see the SMS Provider object.

Delete SMS Provider

The following DELETE request deletes an SMS provider.

curl -X DELETE \
'https://api.carrierx.com/core/v2/admin/sms/providers/36e82093-21f7-487f-b8c0-c919fcf56a86' \
-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 SMS provider, targeted by secure ID.

Method	URL
DELETE	/admin/sms/providers/{provider_sid}

Path Arguments

Parameter	Data Type	Description
provider_sid `required`	string	The SMS provider secure ID.

If the SMS provider with the specified secure ID is used by at least one phone number, it will not be deleted and the "SMS provider is used by 1 phonenumbers" error message will be returned.

Rate Object

Attribute	Data Type	Description
country_code	string	The ISO 3166-1 alpha-3 three-letter country code of this rate.
country_name	string	The common name of the country of this rate.
mcc	integer	Mobile country code for this rate.
mnc	integer	Mobile network code for this rate.
network	string	The name of the network used for this rate.
operator	string	The name of the operator used for this rate.
price	number	The price in US dollars used for this rate.

Get Outbound Rates

The following GET request returns outbound rates for a partner.

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

A successful request will return a 200 response code with a list of outbound rates for a partner.

{
    "active": "yes",
    "count": 1,
    "effective_date": "2017-10-20T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "country_code": "CZE",
            "country_name": "Czech Republic",
            "mcc": 230,
            "mnc": 4,
            "network": null,
            "operator": null,
            "price": "0.08533"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/sms/rates/outbound/toll?limit=1&offset=1"
    },
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "rates_plan": {
        "name": "sms_retail_rates-2017-10-20",
        "rates_plan_sid": "832d7042-2f40-4a5a-b508-ff4d2a988d7a"
    },
    "total": 1778
}

This request returns a list of outbound rates for a partner. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/sms/rates/outbound/{sub_type}

Path Arguments

Parameter	Data Type	Description
sub_type `required`	string	The message rate deck subtype. Values accepted in this field are: `short_code` `toll` `toll_free`

Download CSV with Outbound Rates

The following GET request returns outbound rates for a partner in CSV format.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/rates/outbound/toll/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 list of outbound rates for a partner in CSV format. This request is enabled for Result Filtering and Field Filtering.

Method	URL
GET	/sms/rates/outbound/{sub_type}/csv

Path Arguments

Parameter	Data Type	Description
sub_type `required`	string	The message rate deck subtype. Values accepted in this field are: `short_code` `toll` `toll_free`

Storage

The Storage API allows partners to upload and store files. Files are stored in containers.

Container Object

This section outlines the Container 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
allow_publish	boolean	Whether or not the files in the container can be published.
allowed_classifications	array	Any file with a classification not appearing on this list will be rejected. Values accepted in this field are: `archive` `document` `executable` `media` `unknown`
available_bytes_percent	integer	The percentage of bytes available.
available_files_percent	integer	The percentage of files available.
blocked_classifications	array	Any file with a classification on this list will be rejected. Values accepted in this field are: `archive` `document` `executable` `media` `unknown`
container_sid	string	The container secure ID.
durability_class	string	How the data is stored. At this time, only the default value `unassigned` is available.
encrypted	boolean	Whether or not the data is stored on a encrypted disk. The default value for this field is `false`. Note that this value cannot be changed after the Container object has been created.
integer_key_1	integer	A user-defined integer key.
integer_key_2	integer	A user-defined integer key.
name	string	The container name.
parent_container_sid	string	The parent container secure ID. If set, and referenced file no longer exists, the container will be deleted.
partner_sid	string	The secure ID of the partner associated with the container.
publish_domain	string	The domain URL that will be used to publish the files.
quota-bytes	integer	The maximum number of bytes that can be stored in the container.
quota_files	integer	The maximum number of files that can be stored in the container.
string_key_1	string	A user-defined string key.
string_key_2	string	A user-defined string key.
total_bytes	integer	The total size of files in bytes that are stored in the container.
total_files	integer	The total number of files that are stored in the container.
unique	boolean	Whether or not the container key set (`integer_key_1`, `integer_key_2`, `string_key_1`, and `string_key_2`) must be unique. If you create a container with the `unique` attribute set to `true`, other unique containers (that also have `unique` set to `true`) with the same container key set will not be created. Please set this field when the Container object is initially created to avoid errors. The default value for this field is `false`.

Create Container

The following POST request creates a container.

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Container object.

{
    "allow_publish": true,
    "allowed_classifications": [],
    "available_bytes_percent": 100,
    "available_files_percent": 100,
    "blocked_classifications": [],
    "container_sid": "a291fe99-43d6-446f-a63e-91f93030dc7e",
    "durability_class": "unassigned",
    "encrypted": false,
    "integer_key_1": null,
    "integer_key_2": null,
    "name": "N/A",
    "parent_container_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish_domain": "https://storage.carrierx.com",
    "quota_bytes": 1073741824,
    "quota_files": 100,
    "string_key_1": null,
    "string_key_2": null,
    "total_bytes": 0,
    "total_files": 0,
    "unique": false
}

This request creates a Container object.

Method	URL
POST	/storage/containers

Body Arguments

JSON representation of the fields and values of the Container object to be created. There are no fields required to create a container.

To view all fields that appear in the Container object, see the Container Object.

Get Containers

The following GET request returns containers.

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

A successful request will return a 200 response code with a serialized copy of the Container object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "allow_publish": true,
            "allowed_classifications": [],
            "available_bytes_percent": 100,
            "available_files_percent": 100,
            "blocked_classifications": [],
            "container_sid": "a291fe99-43d6-446f-a63e-91f93030dc7e",
            "durability_class": "unassigned",
            "encrypted": false,
            "integer_key_1": null,
            "integer_key_2": null,
            "name": "N/A",
            "parent_container_sid": null,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "publish_domain": "https://storage.carrierx.com",
            "quota_bytes": 1073741824,
            "quota_files": 100,
            "string_key_1": null,
            "string_key_2": null,
            "total_bytes": 0,
            "total_files": 0,
            "unique": false
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of containers that are available for files upload. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/storage/containers

Get Container by SID

The following GET request returns a container, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Container object.

{
    "allow_publish": true,
    "allowed_classifications": [],
    "available_bytes_percent": 100,
    "available_files_percent": 100,
    "blocked_classifications": [],
    "container_sid": "a291fe99-43d6-446f-a63e-91f93030dc7e",
    "durability_class": "unassigned",
    "encrypted": false,
    "integer_key_1": null,
    "integer_key_2": null,
    "name": "N/A",
    "parent_container_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish_domain": "https://storage.carrierx.com",
    "quota_bytes": 1073741824,
    "quota_files": 100,
    "string_key_1": null,
    "string_key_2": null,
    "total_bytes": 0,
    "total_files": 0,
    "unique": false
}

This request returns a container, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/storage/containers/{container_sid}

Path Arguments

Parameter	Data Type	Description
container_sid `required`	string	The container secure ID.

Update Container

The following PATCH request updates a container, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-H 'Content-Type: application/json' \
--data-binary '{"integer_key_1":"39984"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Container object.

{
    "allow_publish": true,
    "allowed_classifications": [],
    "available_bytes_percent": 100,
    "available_files_percent": 100,
    "blocked_classifications": [],
    "container_sid": "a291fe99-43d6-446f-a63e-91f93030dc7e",
    "durability_class": "unassigned",
    "encrypted": false,
    "integer_key_1": 39984,
    "integer_key_2": null,
    "name": "N/A",
    "parent_container_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish_domain": "https://storage.carrierx.com",
    "quota_bytes": 1073741824,
    "quota_files": 100,
    "string_key_1": null,
    "string_key_2": null,
    "total_bytes": 0,
    "total_files": 0,
    "unique": false
}

Containers can be updated using a PATCH or PUT request. A PATCH request requires passing the container secure ID through the query URL, and the values to be updated through the request body. A PUT request requires passing the container secure ID through the query URL, and passing the entire Container object through the request body.

Method	URL
PATCH	/storage/containers/{container_sid}
PUT	/storage/containers/{container_sid}

Path Arguments

Parameter	Data Type	Description
container_sid `required`	string	The container secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

allow_publish
allowed_classifications
blocked_classifications
integer_key_1
integer_key_2
name
publish_domain
string_key_1
string_key_2

To view all fields that appear in the Container object, see the Container Object.

Delete Container

The following DELETE request deletes a container.

curl -X DELETE \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-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 container, targeted by secure ID.

Method	URL
DELETE	/storage/containers/{container_sid}

Path Arguments

Parameter	Data Type	Description
container_sid `required`	string	The container secure ID.

File Object

This section outlines the File 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
container_sid	string	The secure ID of the container which this file belongs to.
content_classification	string	The content classification.
content_duration	integer	The duration of the file. This field cannot be modified.
content_format	string	The format of the uploaded file. This field cannot be modified.
content_transcoding_progress	string	The progress of the content transcoding. This field cannot be modified.
date_modified	string	The date when the last update of the file took place.
desired_bitrate	string	The desired bit rate for audio and video files.
desired_format	string	The desired format for audio and video files. The default value is `mp3`. Refer to the table below for all file types supported.
file_access_name	string	The path to the file within the container. This field defaults to the file secure ID with extension, where possible.
file_bytes	integer	The file size.
file_sid	string	The file secure ID.
integer_key_1	integer	A user-defined integer key.
integer_key_2	integer	A user-defined integer key.
lifecycle_action	string	The action to be triggered after `lifecycle_ttl` has elapsed. The only value accepted in this field at this time is `delete`.
lifecycle_ttl	integer	How long in seconds before the `lifecycle_action` will be triggered. `-1` means indefinite.
mime_type	string	The content type of the file.
name	string	The file name.
parent_file_sid	string	The parent file secure ID. Setting a `parent_sid` forms a folder-like structure. Files can have a `parent_sid` and this will organize them in groups. If this field is set, and the `parent_sid` no longer exists, files associated with this folder-like structure will be deleted.
partner_sid	string	The secure ID of the partner the file belongs to.
publish	string	Whether to publicly serve a file, and how to store it. Values accepted in this field are: `file_access_name` to serve the URL in the following manner: `/c/{container_sid}/{file_access_name}` `file_sid` to serve the URL in the following manner: `/f/{file_sid}` `no` to not serve the URL via public HTTP.
publish_uri	string	The web accessible URI where the file can be retrieved. This value is only applicable if `publish` is set to `true`.
string_key_1	string	A user-defined string key.
string_key_2	string	A user-defined string key.
type	string	The type of the file. Values accepted in this field are: `file` is the default value `audio` verifies the file type, adds appropriate fields, and allows the ability to transcode to another audio format `video` verifies the file type, and acts similarly to the `audio` type `conference` is less commonly used
unique	boolean	Whether or not the file key set (`integer_key_1`, `integer_key_2`, `string_key_1`, and `string_key_2`) must be unique. If you create a file with the `unique` attribute set to `true`, other unique files (that also have `unique` set to `true`) with the same file key set will not be created. Please set this field when the File object is initially created to avoid errors. The default value for this field is `false`.

desired_format

The following table outlines the capabilities attached to each file format. The column Duration Detection will be marked yes if the file format will detect the duration of the file.

Transcode to Codec will be marked yes if files can be transcoded to this file format. Transcode from Codec will be marked yes if files can be transcoded from this file format. For example, files can be transcoded from wav to mp3 because the former can be transcoded from and the latter can be transcoded to.

Format	Duration Detection	Transcode to Codec	Transcode from Codec
aac	yes	yes	no
al, alaw	yes	yes	yes
flac	yes	yes	yes
g722	yes	yes	yes
mp3	yes	yes	yes
mp4, m4a	yes	yes	no
ogg	yes	yes	yes
ul, ulaw	yes	yes	yes
wav	yes	yes	yes

Upload File

The following POST request uploads a file to a container.

curl -X POST \
'https://api.carrierx.com/core/v2/storage/files' \
-F 'file_object={"container_sid":"cb05c1f4-2398-432c-8314-cc306156281c"}' \
-F 'data=@4931.mp3' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the File object.

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_modified": "2019-01-22T18:13:30.900Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",
    "file_bytes": 29799,
    "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": null,
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "4931.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "type": "file",
    "unique": false
}

This request uploads a file to the specified container. If unique is set to true, no two files can have the same set of keys and values.

Method	URL
POST	/storage/files

Form Arguments

Parameter	Data Type	Description
data `required`	file path	The path of the file to be uploaded.
file_object `required`	object	The fields and values of the file to be uploaded. Refer to the File Object for a list of all fields and values that appear in the File object.

Get Files

The following GET request returns files from a container.

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

A successful request will return a 200 response code with a serialized copy of the File object.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
            "content_classification": "unknown",
            "content_duration": null,
            "content_format": "mp3",
            "content_transcoding_progress": null,
            "date_modified": "2019-01-22T18:13:30.900Z",
            "desired_bitrate": null,
            "desired_format": null,
            "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",
            "file_bytes": 29799,
            "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",
            "integer_key_1": null,
            "integer_key_2": null,
            "lifecycle_action": null,
            "lifecycle_ttl": -1,
            "mime_type": "audio/mpeg",
            "name": "4931.mp3",
            "parent_file_sid": null,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "publish": "file_sid",
            "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
            "string_key_1": null,
            "string_key_2": null,
            "type": "file",
            "unique": false
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of files. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/storage/files

Get File by SID

The following GET request returns a file, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/storage/files/f6070be2-9abd-4726-870c-c86c9aac5c7e' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the File object.

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_modified": "2019-01-22T18:13:30.900Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",
    "file_bytes": 29799,
    "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": null,
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "4931.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "type": "file",
    "unique": false
}

This request returns a file, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/storage/files/{file_sid}

Path Arguments

Parameter	Data Type	Description
file_sid `required`	string	The file secure ID.

Update File

The following PATCH request updates a file, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/storage/files/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"new_name"}'' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the File object.

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_modified": "2019-01-22T18:13:30.900Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",
    "file_bytes": 29799,
    "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": null,
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "new_name",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "type": "file",
    "unique": false
}

A file can be updated through PATCH and PUT requests. A PATCH request requires the file secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the file secure ID passed in the query URL, as well as the entire File object passed in the query body.

Method	URL
PATCH	/storage/files/{file_sid}
PUT	/storage/files/{file_sid}

Path Arguments

Parameter	Data Type	Description
file_sid `required`	string	The file secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

integer_key_1
integer_key_2
lifecycle_action
lifecycle_ttl
name
string_key_1
string_key_2

To view all fields that appear in the File object, see the File Object.

Delete File

The following DELETE request deletes a file.

curl -X DELETE \
'https://api.carrierx.com/core/v2/storage/files/f6070be2-9abd-4726-870c-c86c9aac5c7e' \
-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 file, targeted by secure ID.

Method	URL
DELETE	/storage/{file_sid}

Path Arguments

Parameter	Data Type	Description
file_sid `required`	string	The file secure ID.

Trunk Groups

Trunk groups hold settings to determine to which trunk calls are sent. Trunk groups consist of one or more trunks. It is possible to create a trunk group with no trunks, but no trunk without a trunk group.

Trunk Group Object

This section outlines the Trunk Group 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
acls	object	The Access Control Lists associated with the trunk group. Refer to the table below for more information.
P external_handlers	array	The list of the external handlers objects that will accept the requests and return a set of actions to perform. Refer to the table below for more information.
name	string	The trunk group name. If no value is passed at creation, the value assigned will be `N/A`.
partner_sid	string	The secure ID of the partner associated with the Trunk Group.
routing_data	object	The additional routing data for trunks.
routing_type	string	The routing type for trunks. Values accepted in this field are `failover` and `round_robin`. For trunk groups with `routing_type` set to `failover`, CarrierX will attempt to call the trunk with the lowest `priority` value first. If the call fails, attempts will be made to call other trunks one by one in order of `priority`. For trunk groups with `routing_type` set to `round_robin`, the calls are sent to all the trunks, distributed among them according to their `weight` value. The default value is `failover`.
soft_failure_codes	string	The SIP codes on the basis of which Trunk failure is defined, separated by `;`.
soft_failure_cooldown	string	The time in seconds to wait if the trunk is down.
transformations	object	The transformations associated with the trunk group. Refer to the transformations section for more information.
trunk_group_sid	string	The trunk group secure ID.
trunks	object	The trunks of the trunk group. Refer to the table below for more information.

acls

Attribute	Data Type	Description
access_control_rules	array	The list of Access Control Rule secure IDs.
direction	string	The direction for the Access Control List. Values accepted in this field are: `inbound`, `outbound`, and `any`.
sms_action_false	string	The action to be executed for SMS messages if none of Access Control Rules are applied. Values accepted in this field are `accept` and `reject`.
sms_action_true	string	The action to be executed for SMS messages if any of Access Control Rules are applied. Values accepted in this field are `accept` and `reject`.
voice_action_false	string	The action to be executed for calls if none of Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `reject503`.
voice_action_true	string	The action to be executed for call if any of Access Control Rules are applied. Values accepted in this field are: `accept`, `reject403`, and `reject503`.

external_handlers

Attribute	Data Type	Description
direction	string	The direction of the call that will be processed by the external handlers. Values accepted in this field are: `inbound` for the incoming calls `outbound` for the outgoing calls `any` for any call direction
error_handler	string	The action to be executed when the external handler returns an error or fails to respond within the specified timeout. Values accepted in this field are: `ignore` will ignore the error and continue to treat the call as if the handler did not exist `reject403` will reject the call with the `403` status code `reject503` will reject the call with the `503` status code The default value is `ignore`.
timeout	integer	The maximum time for the external handler to respond in milliseconds. The default value is `250` (i.e., 250 milliseconds).
url	string	The external handler URL.

Sample JSON data of the POST request made to the external handler URL.

{
  "Allow" : [
    "INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH, MESSAGE"
  ],
  "Call-ID" : [
    "243b35b872d5bb005af22dd9339e8149@10.1.10.190"
  ],
  "Contact" : [
    {
      "header_parameters" : {},
      "host" : "10.1.5.200:5060",
      "name" : "",
      "raw" : "<sip:15162065613@10.1.5.200:5060>",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Content-Length" : [
    "349"
  ],
  "Content-Type" : [
    "application/sdp"
  ],
  "CSeq" : [
    "103 INVITE"
  ],
  "Date" : [
    "Wed, 20 May 2020 08:46:17 GMT"
  ],
  "Diversion" : [
    {
      "header_parameters" : {
        "reason" : "unknown"
      },
      "host" : "null",
      "name" : "",
      "raw" : "<sip:19512623062@null>;reason=unknown)",
      "uri_parameters" : {},
      "user" : "19512623062"
    }
  ],
  "From" : [
    {
      "header_parameters" : {
        "tag" : "as69da6efa"
      },
      "host" : "10.1.10.190",
      "name" : "IO",
      "raw" : "\"IO\" <sip:15162065613@10.1.10.190>;tag=as69da6efa",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Max-Forwards" : [
    "69"
  ],
  "P-Charging-Vector" : [
    "icid-value=ab5fc4ee59;icid-generated-at=12.7.193.171"
  ],
  "Remote-Party-ID" : [
    {
      "header_parameters" : {
        "screen" : "no",
        "privacy" : "off",
        "party" : "calling"
      },
      "host" : "10.1.10.190",
      "name" : "IO",
      "raw" : "\"IO\" <sip:15162065613@10.1.10.190>;party=calling;privacy=off;screen=no",
      "uri_parameters" : {},
      "user" : "15162065613"
    }
  ],
  "Supported" : [
    "replaces, timer"
  ],
  "To" : [
    {
      "header_parameters" : {},
      "host" : "10.1.10.190:5060",
      "name" : "",
      "raw" : "<sip:19512623062@10.1.10.190:5060>",
      "uri_parameters" : {},
      "user" : "19512623062"
    }
  ],
  "User-Agent" : [
    "VirtualPBX"
  ],
  "X-Src-IP" : [
    "10.1.5.200:5060"
  ],
  "X-Src-UID" : [
    "92d04fa7-f86f-4acd-a589-860569201845"
  ],
  "X-Src-URI" : [
    "19512623062"
  ]
}

In case the external_handlers list is not empty, when the call reaches this trunk group, a POST request will be made to the external handler URL (url) with the JSON containing SIP headers as its data. Refer to the table below for the detailed explanation of each SIP header.

Attribute	Description
Allow	The list of the supported SIP methods separated by commas.
Call-ID	A globally unique identifier for the call, which is a combination of a random string and the sender’s host name or IP address separated by the `@` character.
Contact	Contains the SIP URI that can be used to contact the sender. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Content-Length	The number of bytes in the message body.
Content-Type	Specifies the type of the SIP message content.
CSeq	The command sequence header that contains a sequence integer and the request name.
Date	The request date and time.
Diversion	Contains the information about the redirection of the call. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
From	Contains the information that identifies the sender of the message. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Max-Forwards	An integer in the range of `0`-`255` that is used to indicate the maximum number of hops that a SIP request may take.
P-Charging-Vector	Is used to coordinate the charging records accumulated as the call is passed through different network entities.
Remote-Party-ID	Enables popular services as well as some regulatory and public safety requirements. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
Supported	Lists the option tags for the supported extensions. If empty, it means that no extensions are supported.
To	Identifies the receiver of the message. The parameters included in this header are: `header_parameters`, `host`, `name`, `uri_parameters`, and `user`. These parameters are included as separate values and as a `raw` representation of these parameters used for SIP communication.
User-Agent	Is used to convey information about the user agent originating the request.
X-*	Custom headers used to specify additional information about the source originating the request (IP, UID, URI, etc.)

The external handler must be able to respond with a list of zero or more actions to perform. Refer to the sample below for more details on the actions accepted in the response.

External Handler Response

Sample external_handlers response with a reject action.

[
  {
    "action": "reject",
    "operands": ["unavailable"]
  }
]

Currently, only the reject action is supported. The external handler must respond with the reject value as an action, and one or more operands, which explain the reject reason, from the list:

Reason	Status Code	Description
bad-gateway	502 Bad Gateway	Network is out of order and the call cannot be accepted.
busy	600 Busy Everywhere	All possible destinations are busy.
busy-here	486 Busy Here	The destination is busy at the current location.
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.
forbidden	403 Forbidden	The destination understood the request, but is refusing to fulfill it.
not-found	404 Not Found	The destination could not be found.
rejected	403 Rejected	The destination understood the request, but is refusing to fulfill it.
unavailable	503 Service Unavailable	Temporary failure.

trunks

Attribute	Data Type	Description
call_type	string	The call type. Values accepted in this field are: `sip_only`, `regular`, and `redirect_302`.
codec	string	The supported codecs.
endpoint_sid	string	The secure ID of the endpoint associated with the Trunk.
in_capacity	integer	The maximum number of simultaneous inbound calls. The default value for this field is `0`, which means unlimited simultaneous inbound calls.
name	string	The trunk name.
out_capacity	integer	The maximum number of simultaneous outbound calls. The default value for this field is `0`, which means unlimited simultaneous outbound calls.
trunk_sid	string	The trunk secure ID.

Create Trunk Group

The following POST request creates a trunk group.

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true' \
-H 'Content-Type: application/json' \
--data-binary "{"name":"New Trunk Group", "trunks":[{"name": "Trunk1", "endpoint_sid": ""}]}" \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk Group object.

{
  "trunk_group_sid": "503167ea-b8a5-4a5d-97e3-d684884da1d8",
  "name": "New Trunk Group",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "routing_type": "failover",
  "routing_data": null,
  "soft_failure_cooldown": 120,
  "soft_failure_codes": "408;",
  "acls": [],
  "trunks": [
      {
          "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
          "name": "Trunk1",
          "endpoint_sid": null,
          "in_capacity": 0,
          "out_capacity": 0,
          "call_type": "regular",
          "codec": null,
          "in_rfc_4694_mode": "cut_all",
          "out_rfc_4694_mode": "cut_all",
          "transformations": []
      }
  ],
  "transformations": []
}

This request creates a new trunk group with or without trunks.

Method	URL
POST	/trunks_groups

Query Arguments

Parameter	Data Type	Description
with_trunks	boolean	Determines whether or not to create a trunk group with one or more trunks.

Body Arguments

JSON representation of the fields and values of the trunk group to be created. No fields are required to create a trunk group.

To view all fields that appear in the Trunk Group object, see the Trunk Group Object.

Get Trunk Groups

The following GET request returns trunk groups.

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "acls": [],
            "name": "Trunk Group for name",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "routing_data": null,
            "routing_type": "failover",
            "soft_failure_codes": "408;",
            "soft_failure_cooldown": 120,
            "transformations": [],
            "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
            "trunks": [
                {
                    "allow_forward": "disable",
                    "call_type": "regular",
                    "codec": null,
                    "endpoint_sid": null,
                    "in_capacity": 0,
                    "name": "N/A",
                    "out_capacity": 0,
                    "relay_sip_headers": [],
                    "in_rfc_4694_mode": "cut_all",
                    "out_rfc_4694_mode": "cut_all",
                    "transformations": [],
                    "trunk_sid": "d01898ac-7dc0-44b2-8bfc-429a0ea95c0f"
                }
            ]
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&limit=1&offset=1"
    },
    "total": 14
}

This request returns a list of trunk groups. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/trunk_groups

Query Arguments

Parameter	Data Type	Description
with_trunks	boolean	Determines whether or not to return trunk groups that have one or more trunks.

Get Trunk Group by SID

The following GET request returns trunk groups, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0?with_trunks=true" \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk Group object.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "acls": [],
            "name": "Trunk Group for name",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "routing_data": null,
            "routing_type": "failover",
            "soft_failure_codes": "408;",
            "soft_failure_cooldown": 120,
            "transformations": [],
            "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
            "trunks": [
                {
                    "allow_forward": "disable",
                    "call_type": "regular",
                    "codec": null,
                    "endpoint_sid": null,
                    "in_capacity": 0,
                    "name": "N/A",
                    "out_capacity": 0,
                    "relay_sip_headers": [],
                    "in_rfc_4694_mode": "cut_all",
                    "out_rfc_4694_mode": "cut_all",
                    "transformations": [],
                    "trunk_sid": "d01898ac-7dc0-44b2-8bfc-429a0ea95c0f"
                }
            ]
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&limit=1&offset=1"
    },
    "total": 14
}

This request returns information for a trunk group, targeted by secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/trunk_groups/{trunk_group_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The Trunk Group secure ID.

Query Arguments

Parameter	Data Type	Description
with_trunks	boolean	Determines whether or not to return trunk groups that have one or more trunks.

Update Trunk Group

The following PATCH request updates a trunk group, targeted by secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "TrunkGroup4"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk Group object.

{
    "acls": [],
    "name": "TrunkGroup4",
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "routing_data": null,
    "routing_type": "failover",
    "soft_failure_codes": "408;",
    "soft_failure_cooldown": 120,
    "transformations": [],
    "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0"
}

A trunk group can be updated through PATCH and PUT requests. A PATCH request requires the trunk group secure ID passed in the query URL, and the specific parameters and values to be updated passed in the request body. A PUT request requires the trunk group secure ID passed in the query URL, as well as the entire Trunk Group object passed in the query body.

Method	URL
PATCH	/trunk_groups/{trunk_group_sid}
PUT	/trunk_groups/{trunk_group_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.

Body Arguments

JSON representation of the fields and values of the Trunk Group object to be updated.

Fields that can be changed are:

acls
name
routing_data
routing_type
soft_failure_codes
soft_failure_cooldown
transformations
trunks

To view all fields that appear in the Trunk Group object, see the Trunk Group Object.

Delete Trunk Group

The following DELETE request deletes a trunk group, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-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 trunk group. All Trunks that have been created under the selected trunk group will be also deleted.

Method	URL
DELETE	/trunk_groups/{trunk_group_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.

Trunk Object

Trunks hold settings that will determine how the system will communicate with an endpoint. Trunks belong to trunk groups. This section goes over the parts of the Trunk object. This is the JSON response that gets returned when a request is successful.

Attribute	Data Type	Description
allow_forward	string	Whether or not to allow forward.
allow_transfer	boolean	Whether or not to allow transfer.
asn_mode	string	Whether or not to allow PASSCALLERCSRC, PASSCALLEECSRC variables for ASN proxy. Values accepted in this field are: `disable` to disable this feature. `read` to allow reading of ASN proxy flags. `write` to allow writing of ASN proxy flags. `read and write` to allow both reading and writing of ASN proxy flags. The default value is `disable`.
call_type	string	The call type. Values accepted in this field are: `redirect_302` for 302 redirect `regular` for with media. `sip_only` for SIP only The default value is `regular`.
codec	string	The supported codec.
endpoint_sid	string	The endpoint secure ID of the Endpoint associated with this trunk.
id	string	The trunk internal ID.
in_capacity	integer	The maximum number of simultaneous inbound calls. `0` means unlimited and is the default value.
in_identity_mode	string	Controls when and how the information about Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers is passed. Values accepted in this field are: `passthrough` `never` `always` `rewrite_from` See the `out_identity_mode` parameter below for more information on this. The default value is `passthrough`.
in_rfc_4694_mode	string	Controls whether the number portability parameters for the “tel” URI are accepted for the incoming leg. Values accepted in this field are: `accept_all` for accepting all the RFC-4694 parameters as they are. `cic_only` for accepting CIC parameter information only. `cut_all` for cutting all the RFC-4694 parameters information off the incoming leg. `rn_npdi` for accepting the information for query to NPDB and routing number only. The default value is `cut_all`.
location_sid	string	Secure ID of the location object that identifies the Trunk Object as belonging to a specific location.
name	string	The trunk name.
out_capacity	integer	The maximum number of simultaneous outbound calls. `0` means unlimited and is the default value.
out_identity_mode	string	Controls whether Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers are passed. The behavior depends on the `in_identity_mode` value and RPID/PAI headers presence, and is described in respect to the accepted values below. `passthrough` and RPID/PAI headers are present: if `in_identity_mode = passthrough` or `in_identity_mode = never`, then ‘From’ remains unchanged, PAI header is set to RPID/PAI, privacy flags are preserved. if `in_identity_mode = always`, then ‘From’ remains unchanged, PAI header is not sent. if `in_identity_mode = rewrite_from`, then ‘From’ is set to RPID/PAI, PAI header is not sent. `never` or RPID/PAI headers are missing: if `in_identity_mode = passthrough` or `in_identity_mode = always` or `in_identity_mode = rewrite_from`, then ‘From’ remains unchanged, PAI header is not sent. if `in_identity_mode = never`, then ‘From’ remains unchanged, PAI header is set to the ‘From’ value. The default value is `passthrough`.
out_rfc_4694_mode	string	Controls whether the number portability parameters for the “tel” URI are passed to the outgoing leg. Values accepted in this field are: `accept_all` for passing all the RFC-4694 parameters as they are. `cic_only` for passing CIC parameter information only. `cut_all` for cutting all the RFC-4694 parameters information off the outgoing leg. `rn_npdi` for passing the information for query to NPDB and routing number only. The default value is `cut_all`.
priority	integer	Allows to change the routing order for trunks inside a trunk group with the `routing_type` set to `failover`. Lower values have higher priority. The default value is `0`.
relay_sip_headers	array	The list of the incoming leg headers that must be relayed to the outgoing leg. Regular expressions can be used instead of complete header names (e.g., the `X-.*` value will relay all the X-headers).
transformations	object	The transformations to apply to the trunk. Refer to the transformations section for more information.
trunk_sid	string	The trunk secure ID.
weight	integer	Allows to distribute the calls among the trunks inside a trunk group with the `routing_type` set to `round_robin`. Trunks with bigger values will receive more calls compared to trunks with smaller values.

Please note, that identity information (the in_identity_mode and out_identity_mode parameters) is supported using either RPID or PAI headers. However, when placing the outbound call leg, PAI format will always be used for sending.

Create Trunk

The following POST request 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 '{"name": "trunk01", "endpoint_sid": null}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk object.

{
    "allow_forward": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "priority": 0,
    "in_capacity": 0,
    "name": "trunk01",
    "out_capacity": 0,
    "in_identity_mode": "passthrough",
    "out_identity_mode": "passthrough",
    "relay_sip_headers": [],
    "in_rfc_4694_mode": "cut_all",
    "out_rfc_4694_mode": "cut_all",
    "transformations": [],
    "trunk_sid": "4c51c85c-5355-4a91-bf1e-f33d731bcfa9"
}

This request will add a new trunk to the selected trunk group.

Method	URL
POST	/trunk_groups/{trunk_group_sid}/trunks

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.

Body Arguments

JSON representation of the fields and values of the Trunk object to be created. There are no fields required to create a Trunk object.

To view all fields that appear in the Trunk object, see the Trunk Object.

Get Trunks

The following GET request returns trunks, targeted by trunk group secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk object.

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "allow_forward": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
            "priority": 0,
            "in_capacity": 0,
            "name": "N/A",
            "out_capacity": 0,
            "in_identity_mode": "passthrough",
            "out_identity_mode": "passthrough",
            "relay_sip_headers": [],
            "in_rfc_4694_mode": "cut_all",
            "out_rfc_4694_mode": "cut_all",
            "transformations": [],
            "trunk_sid": "aed1c137-8cbf-417c-8c41-e181f425826b"
        },
        {
            "allow_forward": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": null,
            "priority": 0,
            "in_capacity": 0,
            "name": "trunk01",
            "out_capacity": 0,
            "in_identity_mode": "passthrough",
            "out_identity_mode": "passthrough",
            "relay_sip_headers": [],
            "in_rfc_4694_mode": "cut_all",
            "out_rfc_4694_mode": "cut_all",
            "transformations": [],
            "trunk_sid": "4c51c85c-5355-4a91-bf1e-f33d731bcfa9"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 2
}

This request returns a list of trunks. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/trunk_groups/{trunk_group_sid}/trunks

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.

Get Trunk by SID

The following GET request returns a trunk, targeted by trunk group and trunk secure IDs.

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk object.

{
    "allow_forward": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
    "priority": 0,
    "in_capacity": 0,
    "name": "N/A",
    "out_capacity": 0,
    "in_identity_mode": "passthrough",
    "out_identity_mode": "passthrough",
    "relay_sip_headers": [],
    "in_rfc_4694_mode": "cut_all",
    "out_rfc_4694_mode": "cut_all",
    "transformations": [],
    "trunk_sid": "aed1c137-8cbf-417c-8c41-e181f425826b"
}

This request returns data about a trunk, targeted by trunk and trunk group secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.
trunk_sid `required`	string	The trunk secure ID.

Update Trunk

The following PATCH request updates a trunk, targeted by trunk group and trunk secure ID.

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "trunk_new_name", "endpoint_sid": null}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Trunk object.

{
    "allow_forward": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "priority": 0,
    "in_capacity": 0,
    "name": "trunk_new_name",
    "out_capacity": 0,
    "in_identity_mode": "passthrough",
    "out_identity_mode": "passthrough",
    "relay_sip_headers": [],
    "in_rfc_4694_mode": "cut_all",
    "out_rfc_4694_mode": "cut_all",
    "transformations": [],
    "trunk_sid": "aed1c137-8cbf-417c-8c41-e181f425826b"
}

Trunks can be updated using a PATCH or PUT request. A PATCH request requires passing the trunk group and trunk secure IDs through the query URL, and the fields and values to be updated through the request body. A PUT request requires passing the trunk SID through the query URL, and passing the entire Trunk object through the request body.

Method	URL
PATCH	/trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}
PUT	/trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.
trunk_sid `required`	string	The trunk secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be changed are:

call_type
codec
in_capacity
name
out_capacity
transformations

To view all fields that appear in the Trunk Group object, see the Trunk Group Object.

Delete Trunk

The following DELETE request deletes a trunk, targeted by trunk group and trunk secure ID.

curl -X DELETE \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-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 trunk, targeted by trunk and trunk group secure ID.

Method	URL
DELETE	/trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}

Path Arguments

Parameter	Data Type	Description
trunk_group_sid `required`	string	The trunk group secure ID.
trunk_sid `required`	string	The trunk secure ID.

Verification

Verification enables the system to send out verification emails and verify the email address through a token. Contact technical support at support@carrierx.com to enable using verification.

Verification Email Object

This section goes over the parts of the Verification Email object. This is the JSON response that gets returned when a request is successful.

Attribute	Data Type	Description
base_url	URL	The URL of the page to be re-addressed to after email verification.
email_template_sid	string	The email template secure ID.
partner_sid	string	The partner secure ID.
status	string	The status of the verification. Values accepted in this field are: `created`, `sent_email`, and `verified`.
to_address	string	The verified email address.

Send Verification SMS

The following POST request sends a verification SMS.

curl -X POST
'https://api.carrierx.com/core/v2/verification/sms?from_did=15162065574&to_did=18057224756&message=Your+verification+code+is+' \
-H "Content-Type: application/json"
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code.

{
    "code": "6664",
    "message_sid": "bd874824-826c-4c7b-860b-6da705c8d2e8"
}

This request sends an outbound message with a unique code generated by the system. A verification SMS message has the same structure as a normal SMS message, but the direction will always be outbound and the message string will include a code generated by the system. Refer to the SMS Object for a list of all fields that appear in the SMS object.

Method	URL
POST	/verification/sms

Query Arguments

Parameter	Data Type	Description
code_length	integer	The length of the verification code.
code_type	string	The type of code to generate. Values accepted in this field are: `alphabetical_lower` `alphabetical_upper` `alphabetical` `alphanumeric_lower` `alphanumeric_upper` `alphanumeric` `numeric`
did_group_sid	string	The DID group secure ID.
from_did `required`	string	The phone number of the message originator in E.164 format.
message	string	The message to be shown before the unique code. The default string is “Your verification code is”.
to_did `required`	string	The phone number of the recipient in E.164 format.

Send Verification Email

The following POST request sends a verification email.

curl -X POST \
'https://api.carrierx.com/core/v2/verification/email' \
--data-binary '{"to_address": "jsmith@carrierx.com"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

A successful request will return a 200 response code with a serialized copy of the Verification Email object.

{
    "base_url": "https://www.carrierx.com/confirmed",
    "email_template_sid": "3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba",
    "partner_sid": null,
    "status": "sent_email",
    "to_address": "jsmith@carrierx.com"
}

This request sends a verification email to the specified email address.

Method	URL
POST	/verification/email

Body Arguments

JSON representation of the verification email to be sent. To send a verification email, to_address or partner_sid must be provided. If partner_sid is provided, the verification email will be sent to the owner_email of that partner.

To view all fields that appear in the Verification Email object, refer to the Verification Email Object.

Verify Email by Token

This request verifies the email address of a partner through a token. The token is passed in the query URL.

Method	URL
POST	/verification/email/tokens/{token}

Path Arguments

Parameter	Data Type	Description
token `required`	string	The verification email token.

Email Template Object

This section goes over the parts of the Email Template object. This is the JSON response that gets returned when a request is successful.

Attribute	Data Type	Description
bcc_addresses	string	The addresses of the recipients to appear in the BCC field.
cc_addresses	string	The addresses of the recipients to appear in the CC field.
from_address	string	The address showing the email sender.
html_body	string	The email HTML body.
name	string	The name of the email template.
subject	string	The email subject title.
template_sid	string	The template secure ID.
text_body	string	The email text body.
to_addresses	string	The addresses of the recipients.
type	string	The template type.

Get Email Templates

The following GET request returns email templates.

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

This request returns a 200 response with a serialized copy of the Email Template object.

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "bcc_addresses": "jsmith@freeconferencecall.com",
            "cc_addresses": null,
            "from_address": "noreply@carrierx.com",
            "name": "Forgot Partner Password template",
            "subject": "QA: CarrierX Password Reset",
            "template_sid": "465eb46b-05a7-4251-b89c-e99f2b81509b",
            "text_body": "To complete your password reset, please click the link below:\n${base_url}?token=${uuid}\n\nYou are receiving this email because someone has initiated a password reset on\nyour account.\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
            "to_addresses": null,
            "type": "forgot_partner_password"
        },
        {
            "bcc_addresses": "jsmith@freeconferencecall.com",
            "cc_addresses": null,
            "from_address": "noreply@carrierx.com",
            "name": "Email Verification template",
            "subject": "QA: CarrierX Email Verification",
            "template_sid": "3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba",
            "text_body": "Hello!\n \nPlease confirm your email address by pasting this link into your browser:\n${base_url}?token=${uuid}\n \nYou are receiving this email because you requested account access to\nhttp://www.carrierx.com/\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
            "to_addresses": null,
            "type": "email_address_verification"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 2
}

This request returns the list of existing email templates. This request is enabled for Pagination, Result Filtering, and Field Filtering.

Method	URL
GET	/verification/email/templates

Get Email Template by SID

The following GET request returns an email template, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/verification/email/templates/465eb46b-05a7-4251-b89c-e99f2b81509b?exclude_fields=html_body' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This request returns a 200 response including an html_body field.

{
    "bcc_addresses": "jsmith@freeconferencecall.com",
    "cc_addresses": null,
    "from_address": "noreply@carrierx.com",
    "name": "Forgot Partner Password template",
    "subject": "QA: CarrierX Password Reset",
    "template_sid": "465eb46b-05a7-4251-b89c-e99f2b81509b",
    "text_body": "To complete your password reset, please click the link below:\n${base_url}?token=${uuid}\n\nYou are receiving this email because someone has initiated a password reset on\nyour account.\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
    "to_addresses": null,
    "type": "forgot_partner_password"
}

This request returns an Email Template object, targeted by the secure ID. This request is enabled for Field Filtering.

Method	URL
GET	/verification/email/templates/{template_sid}

Path Arguments

Parameter	Data Type	Description
template_sid `required`	string	The template secure ID.