Introduction

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

Refer to the Voice and SMS products page for quick start guides and video tutorials. These hold walk-through instructions on renting phone numbers, as well as configuring SIP trunks, trunk groups, and application endpoints.

Using the REST API

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

Using Postman

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

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

Run in Postman

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

Main Conventions

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

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

Credentials

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

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

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

{
  "count": 2,
  "has_more": false,
  "items": [
      {
          "addresses": [
              {
                  "direction": "any",
                  "ip": "10.1.10.69",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
          "name": "System Gateway",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {},
          "transformations": [],
          "type": "system_gateway",
          "voip_token": null
      },
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flex",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 2
}

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

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

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

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

Requests

Sample request to create Conference endpoint.

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

The requests in CarrierX API are made using the standard REST notation, typical for web services. This includes the URL, to which the request will be sent, the request method, the request related headers, and, optionally, a payload.

Request URL

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

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

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

Request Methods

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

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

POST

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

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

GET

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

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

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

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

PATCH/PUT

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

Sample PATCH request to modify or add a new name record of the nested attributes object.

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

The successful request returns the serialized JSON copy of the created object together with the nested object.

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

Sample PATCH request to add a new name2 record of the nested attributes object of the same Partner object.

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

The successful request returns the serialized JSON copy of the created object together with the modified nested object.

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

Sample PATCH request to modify the entire nested attributes object of the same Partner object.

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

The successful request returns the serialized JSON copy of the created object together with the nested object.

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

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

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

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

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

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

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

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

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

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

DELETE

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

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

Additional Request Parameters

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

Responses

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

Pagination

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

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

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

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

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

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

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

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

The JSON response for a successful query using the pagination parameters offset, limit, and order will include a pagination parameter. The value of pagination will be empty if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include next or previous URLs. These URLs can be used to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL provided in this field.

Pagination Quick Reference

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 batch task, you will have the option to review the items if you set the review field to boolean true value. In this case, your returned JSON status will be pending_review.

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

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

Callbacks

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

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

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

sms and callback_url Callback

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

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

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

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

app_mediator Callback

The following is the app_mediator callback response.

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

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

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 sections: Access Control, Batch, 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.

Sample Access Control List object:

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

Look Up Effective ACLs for Calls

The following GET request returns effective ACLs for calls.

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

A successful request will return a 200 response code with a list of Access Control List objects.

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

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

GET /accesscontrol/effective_acl/calls

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

Required Scopes

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

Query Arguments

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

Look Up Effective ACLs for SMS

The following GET request returns effective ACLS for SMS.

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

A successful request will return a 200 response code with a list of Access Control List objects.

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

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

GET /accesscontrol/effective_acl/sms

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

Required Scopes

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

Query Arguments

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

Access Control Rule Object

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

Sample Access Control Rule object:

{
    "entries": [
        "1800",
        "1615"
    ],
    "field": "to",
    "name": "N/A",
    "operation": "prefix",
    "quantifier": "any",
    "read_only": false,
    "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"
}
Attribute Data Type Description
entries create update array The list of entries to compare against the quantifier field.
field create update string The field from the call or SMS to check. This value will be used in comparison with entries.
name create update string The Access Control Rule name. The value will be set to N/A if not specified otherwise.
operation create update string Determines how the value is checked. Values accepted in this field are:
  • builtin
  • exact
  • prefix
  • regexp
quantifier create update string The type of comparison to be made between entries and field. Values accepted in this field are:
  • all
  • any
  • none
read_only create update boolean Shows whether the Access Control Rule can be modified or not. Values accepted in this field are true and false.
rule_sid read only string The Access Control Rule secure ID.

Create Access Control Rule

The following POST request creates a access control rule.

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

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

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

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

/accesscontrol/rules

Required Scopes

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

Body Arguments

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

Required fields to create an access control rule are:

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

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

Get Access Control Rules

The following GET request returns access control rules matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Access Control Rule objects.

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

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

GET /accesscontrol/rules

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

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

Required Scopes

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

Get Access Control Rule by SID

The following GET request returns an access control rule, targeted by secure ID.

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

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

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

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

GET /accesscontrol/rules/{rule_sid}

Returned ACRs apply to the partner and the parent partner.

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Access Control Rule

The following PATCH request updates the Access Control Rule object, targeted by secure ID, with the values in the request body.

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

A successful request will return a 200 response code with a serialized copy of the updated Access Control Rule object.

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

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

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

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

Required Scopes

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

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete Access Control Rule

The following DELETE request deletes an Access Control Rule, targeted by secure ID.

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

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

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

DELETE /accesscontrol/rules/{rule_sid}

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

Required Scopes

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

Path Arguments

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

Batch

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

Task Object

This section describes the elements of the batch task object.

Sample Task object:

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

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

Create Task

The following POST request creates a batch task.

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

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

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

This request creates a batch task.

/batch/tasks

Required Scopes

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

Body Arguments

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

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

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

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

Get Tasks

The following GET request returns tasks matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Task objects associated with the credentials.

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

This request returns a list of tasks.

GET /batch/tasks

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

Required Scopes

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

Get Task by SID

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

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

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

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

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

GET /batch/tasks/{task_sid}

Required Scopes

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

Path Arguments

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

Update Task

The following PATCH request updates the Task object, targeted by secure ID, with the values in the request body.

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

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

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

This request updates a task, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

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

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

Delete Task

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

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

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

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

DELETE /batch/tasks/{task_sid}

Required Scopes

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

Batch Review

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

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

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

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

Batch Review Response Object

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

Batch Review Item Object

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

Get Task Review Items by SID

The following GET request returns batch task review items, targeted by task secure ID.

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

A successful request will return a 200 response code with a serialized copy of any associated review items.

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

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

GET /batch/tasks/{task_sid}/review_items

Required Scopes

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

Path Arguments

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

Download CSV of Task Review Items by SID

The following GET request returns task review items for a partner in CSV format.

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

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

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

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

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Calls

Calls are communications between two or more phone numbers.

Call Detail Record Object

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

Sample Call Detail Record object:

{
    "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
}
Attribute Data Type Description
date_insert read only string The date when the detail record was inserted into the database.
date_start read only string The date and time when the call was started or the SMS was created.
date_stop read only string The date and time when the call ended or SMS was delivered.
date_talk read only string The date and time when the destination phone number answered.
direction read only string The direction of the call. Values accepted in this field are:
  • any
  • inbound
  • outbound
  • undirected
disconnect_originator read only string The originator of a call drop. The value will be null for SMS.
diversion_dst read only string The destination diversion header.
diversion_src read only string The source diversion header.
dr_sid read only string The secure ID of the record.
duration read only number The call duration in seconds. The value is calculated as date_stopdate_start.
duration_billing read only number The calculated call duration in seconds to set the price.
endpoint_sid_dst read only string The destination endpoint secure ID. If the destination is an external phone number, this value will be populated with the System Gateway secure ID.
endpoint_sid_src read only string The source endpoint secure ID. If the source is an external phone number, this value will be populated with the System Gateway secure ID.
identity read only string The real phone number that the call is coming from. This field is populated from either PAI or RPID.
ip_dst read only string The IP address of the destination of call.
ip_src read only string The IP address of the source of call.
number_billing read only string The subscriber phone number.
number_dst read only string The destination phone number. Values accepted in this field are the calling number if the call is outbound, or the called number if the call is inbound.
number_dst_original read only string The destination phone number before any transformations were applied. This field will populate if this value is different from number_dst.
number_dst_transformed read only string The destination phone number after any transformations were applied. This field will populate if this value is different from number_dst.
number_external read only string The non-subscriber phone number.
number_src read only string The source number. Values accepted in this field are the calling number if the call is outbound, or the called number if the call is inbound.
number_src_original read only string The source phone number before any transformations were applied. This field will populate if this value is different from number_src.
number_src_transformed read only string The source phone number after any transformations were applied. This field will populate if this value is different from number_src.
partner_sid read only string The partner secure ID.
price read only number The price for the detail record.
ref_id read only string The internal ID of the call.
sipcallid_dst read only string The SIP call ID of the destination call.
sipcallid_src read only string The SIP call ID of the source of call.
sipcause read only string The SIP code of the call.
trunk_group_sid_dst read only string The destination trunk group secure ID.
trunk_group_sid_src read only string The source trunk group secure ID.
trunk_sid_dst read only string The destination trunk secure ID.
trunk_sid_src read only string The source trunk secure ID.
type read only string The type of call. Values accepted in this field are:
  • conference_call
  • conference_meeting
  • mediator
  • mms
  • sms
  • telecom
version read only 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 matching the criteria in the request URL.

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

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

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2019-01-18T15:35:03.000Z",
            "date_start": "2019-01-18T15:32:15.589Z",
            "date_stop": "2019-01-18T15:32:19.839Z",
            "date_talk": "2019-01-18T15:32:16.535Z",
            "direction": "inbound",
            "disconnect_originator": "DST",
            "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.

GET /calls/call_drs

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

Required Scopes

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

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

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.

GET /calls/call_drs/{dr_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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

Path Arguments

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

Rate Object

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

Sample Rate object:

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

Rate Call Object

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

Rates Plan Object

Parameter Data Type Description
name read only string The name of the rates plan.
rates_plan_sid read only 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 list of Rate objects.

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

The request returns a list of inbound PSTN rates for calls.

GET /calls/rates/inbound/pstn

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

Download CSV of Inbound PSTN Rates

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

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.

GET /calls/rates/inbound/pstn/csv

This request is enabled for Field Filtering.

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.

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

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

Path Arguments

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

Download CSV of Inbound VoIP Rates

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

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 200 response and a CSV download.

This request returns a CSV of all inbound VoIP rates matching the request criteria.

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

This request is enabled for Field Filtering.

Path Arguments

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

Get Outbound PSTN Rates

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.

GET /calls/rates/outbound/pstn

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

Download CSV of Outbound PSTN Rates

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

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 200 response and a CSV download.

This request returns a CSV of all outbound PSTN rates matching the request criteria.

GET /calls/rates/outbound/pstn/csv

This request is enabled for Field Filtering.

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.

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

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

Path Arguments

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

Download CSV of Outbound VoIP Rates

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

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

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

This request returns a CSV of all outbound PSTN rates matching the request criteria.

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

This request is enabled for Field Filtering.

Path Arguments

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

Countries

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

Country Object

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

Sample Country object:

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

Get Countries

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 list of Country objects.

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

This request returns a list of countries.

GET /countries

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

Required Scopes

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

Get Country by ISO Code

The following GET request returns a country, targeted by ISO code.

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

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.

GET /countries/{country_code}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Get Country by IP Address

The following GET request returns a country, targeted by IP address.

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

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.

GET /countries/ip/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

Parameter Data Type Description
ip_address required string The IPv4 address.

Endpoints

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

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

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

Endpoint Object

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

Sample Endpoint object:

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

Endpoint Address Object

Attribute Data Type Description
direction create update string The direction for the address. Values accepted in this field are: inbound, outbound, and any. The default value for this field is any.
dst_port create update integer If specified, this entry is only valid for calls that reach CarrierX on this port. CarrierX listens on port 5060-5069, and any of these ports may be specified. The default port value is 5060.
ip create update string The IP address.
location_sid create update string The location secure ID.
port create update integer The port. The default port value is 5060.
priority create update integer The priority of the address. Lower values have higher priority. The default value is 0.
sip_password create update string For calls sent to this endpoint and if proxy authentication is required, this password and sip_username will be used. This value overrides the out_sip_password value of the Endpoint object.
sip_username create update string For calls sent to this endpoint and if proxy authentication is required, this username and sip_password will be used. This value overrides the out_sip_username value of the Endpoint object.
transport create update string The protocol for the address. Values accepted in this field are: tcp, tls, and udp. The default value for this field is udp. This field applies to the Third Party endpoint.

Attributes Object

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

Properties Object

Attribute Data Type Description
account_sid read only string The account secure ID.
api_url read only string The URL of the API.
callback_method create update string The callback method used with the Voicemail endpoint. Values accepted in this field are POST and GET. The default value is POST.
callback_url create update string The callback URL used with the Voicemail endpoint. The default value is null.
container_sid create update string The secure ID of the container where recordings will be stored. The default value is null.
greeting create update string The name of the file used as a greeting for the Voicemail endpoint. The default value is null.
login read only string The login for the endpoint.
max_duration create update number The maximum length of the recording in seconds used with the Voicemail endpoint.
password read only 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 a serialized copy of the Endpoint object.

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

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 a serialized copy of the Endpoint object.

{
    "addresses": [
        {
            "direction": "any",
            "ip": "1.1.2.13",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "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 an endpoint.

/endpoints

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

Required Scopes

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

Body Arguments

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

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

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

Get Endpoints

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 list of Endpoint objects.

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "addresses": [
                {
                    "direction": "any",
                    "ip": "1.1.2.13",
                    "location_sid": null,
                    "port": 5060,
                    "priority": 0,
                    "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",
                    "location_sid": null,
                    "port": 5060,
                    "priority": 0,
                    "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.

GET /endpoints

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

Required Scopes

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

Query Arguments

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

Get Endpoint by SID

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

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

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",
            "location_sid": null,
            "port": 5060,
            "priority": 0,
            "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 data for an endpoint, targeted by secure ID.

GET /endpoints/{endpoint_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Query Arguments

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

Update Endpoint

The following PATCH request updates the Endpoint object, targeted by secure ID, with the values in the request body.

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

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

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

This request updates an endpoint, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

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

Delete Endpoint

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

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

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

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

DELETE /endpoints/{endpoint_sid}

Required Scopes

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

Path Arguments

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

Invoices

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

Invoice Object

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

Sample Invoice object:

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

Invoice Item Object

Attribute Data Type Description
amount read only number The invoice item price total.
country_code read only string The ISO 3166-1 alpha-3 code of the DID associated with this invoice.
date_billing_period_end read only string The date and time when the billing period ended.
date_billing_period_start read only string The date and time when the billing period started.
direction read only string The direction of the call or SMS/MMS, either inbound or outbound.
type read only string The type of call 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 read only integer The number of times the item was used.

Invoice Pay Item Object

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

Invoice Tax Item Object

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

Get Invoices

The following GET request returns invoices matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Invoice objects.

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

This request returns a list of invoices.

GET /invoices

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

Required Scopes

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

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

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

GET /invoices/{invoice_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Get Invoice HTML Report by SID

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

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

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

GET /invoices/{invoice_sid}.html

Required Scopes

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

Path Arguments

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

Send Invoice HTML Report by SID to Email Addresses

The following POST request sends an invoice, targeted by secure ID, in HTML format to the email addresses specified in the request.

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

A successful request will return a 204 response code and will send the invoice in HTML format to an email address.

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

/invoices/{invoice_sid}.html/emails

Required Scopes

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

Path Arguments

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

Body Arguments

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

Get Invoice PDF Report by SID

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

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

A successful request will return a 200 response code with the invoice in PDF format.

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

GET /invoices/{invoice_sid}.pdf

Required Scopes

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

Path Arguments

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

Send Invoice PDF Report by SID to Email Addresses

The following POST request sends an invoice, targeted by secure ID, in PDF format to the email addresses specified in the request.

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

A successful request will return a 204 response code and will send the invoice in PDF format to an email address.

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

/invoices/{invoice_sid}.pdf/emails

Required Scopes

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

Path Arguments

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

Body Arguments

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

Lookup

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

Phonenumber Lookup Object

Sample Phonenumber Lookup object

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

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

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

Phonenumber Lookup Detail Object

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

Phonenumber Lookup Detail Carrier Object

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

Phonenumber Lookup Detail Cnam Object

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

Get Details for Phone Number

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

This request returns data for the specified phone number.

GET /lookup/dids/{phonenumber}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Query Arguments

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

Phone Number Lookup Logic

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

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

IP2Location Object

Sample IP2Location object

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

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

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

Get Details for IP Address

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

This request returns data for the specified IP address.

GET /lookup/lookup/ip_addresses/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

OAuth

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

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

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

OAuth Token Object

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

Sample OAuth Token object:

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

Revoke OAuth Token

The following POST request terminates an OAuth token, targeted by the partner client ID and client secret.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

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

/oauth/revoke

Required Scopes

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

Body Arguments

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

Generate OAuth Bearer Token

The following POST request generates an OAuth bearer token for a partner.

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=authorization_code&client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

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

This request generates a token for the partner upon request.

/oauth/token

Required Scopes

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

Body Arguments

Parameter Data Type Description
access_token_expires_in integer The access token expiration in seconds.
client_id required string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret required string The client secret string. This is a unique string representing the registration information provided to the client upon request.
grant_type required string The grant type for the token. Values accepted in this field are:
  • authorization_code
  • password
  • refresh_token
name string The friendly name used to identify the token.
password string The password of the partner (in the case of grant_type = password).
refresh_token string The refresh token (in the case of grant_type = refresh_token).
refresh_token_expires_in integer The refresh token expiration in seconds.
refresh_token_type string The type of request (in the case of grant_type = refresh_token). Values accepted in this field are:
  • access_token
  • new_token
  • refresh_token
scope string The OAuth token visibility scope. Values accepted in this field are:
  • children for the token that will be visible to both the partner and sub-partners.
  • public for the token that will be visible to all partners with access.
  • self for the token that will be visible to the current partner only.
username string The login of the partner (in the case of grant_type = password).

Generate OAuth Bearer Token for Sub-partner

The following POST request generates an OAuth bearer token for a sub-partner.

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

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

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

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

/oauth/token/{partner_sid}

Required Scopes

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

Path Arguments

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

Body Arguments

Parameter Data Type Description
access_token_expires_in integer The access token expiration in seconds.
client_id required string The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret required string The client secret string. This is a unique string representing the registration information provided to the client upon request.
name string The friendly name used to identify the token.
refresh_token_expires_in integer The refresh token expiration in seconds.
scope string The OAuth token visibility scope. Values accepted in this field are:
  • children for the token that will be visible to both the partner and sub-partners.
  • public for the token that will be visible to all partners with access.
  • self for the token that will be visible to the current partner only.

Get All Active OAuth 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.

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

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

GET /oauth/token

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

Required Scopes

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

Get OAuth Token by SID

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

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

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

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

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

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

GET /oauth/token/{token_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update OAuth Token

The following PATCH request updates the OAuth Token object, targeted by secure ID, with the values in the request body.

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

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

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

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

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

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

Required Scopes

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

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

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Get Current Partner

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

This request returns the currently logged-in partner.

GET /oauth/whoami

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

Partners

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

Partner Object

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

Sample Partner object:

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

Partner 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 admin The partner can create admin actions.
admin.delete admin The partner can delete admin actions.
admin.manage admin The partner can create, read, update, and delete admin actions.
admin.read admin The partner can read admin actions.
admin.update admin The partner can update admin actions.
app.create admin The partner can create Apps object actions.
app.delete admin The partner can delete Apps object actions.
app.manage admin The partner can create, read, update, and delete Apps object actions.
app.read admin The partner can read Apps object actions.
app.read_descendant admin The partner can view Apps object detailed records for the inherited partner.
app.update admin The partner can update Apps 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 partners.
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 DID Emergency objects.
phonenumber.emergency.read The partner can read DID Emergency objects.
phonenumber.line_information.manage The partner can create, read, update, and delete DID Line Information objects.
phonenumber.line_information.read The partner can read DID 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 admin preview The partner can create Local Routing Number Order objects.
porting.delete admin preview The partner can delete Local Routing Number Order objects.
porting.manage admin preview The partner can create, read, update, and delete Local Routing Number Order objects.
porting.read admin preview The partner can read Local Routing Number Order objects.
porting.update admin preview The partner can update Local Routing Number Order 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 objects.
rating.delete The partner can delete Rating objects.
rating.manage The partner can create, read, update, and delete Rating objects.
rating.read The partner can read Rating objects.
rating.update The partner can update Rating objects.
shortener.allow_domain_mode_proxypass The partner can set the expired_mode and not_found_mode attributes for the Domain object to proxy_pass.
shortener.allow_domain_secure_required The partner can set the secure attribute for the Domain object to required.
shortener.allow_link_mode_proxypass The partner can set the mode attribute 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 partners.
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 admin The partner can create system actions.
system.delete admin The partner can delete system actions.
system.manage admin The partner can create, read, update, and delete system actions.
system.read admin The partner can read system actions.
system.update admin The partner can update system actions.
trunk_groups.allow_external_handlers_update preview The partner can modify the external_handlers attribute 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 attribute 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.

ACL Object

This object is used with acls and parent_assigned_acls.

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

Create Partner

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

This request creates a partner.

/partners/

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

Required Scopes

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

Body Arguments

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

Required fields to create a partner are:

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

Get Partners

The following GET request returns partners matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Partner objects.

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

This request returns a list of partners.

GET /partners/

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

Required Scopes

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

Get Partner by SID

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

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

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

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

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

GET /partners/{partner_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Partner

The following PATCH request updates the Partner object, targeted by secure ID, with the values in the request body.

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

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

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

This request updates a partner, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete Partner

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

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

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

This request deletes a partner, targeted by secure ID.

DELETE /partners/{partner_sid}

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

Required Scopes

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

Path Arguments

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

Billing Method Object

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

Sample Billing Method object:

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

Register Billing Method

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 'Content-Type: application/json' \
--data-binary '{"type":"visa", "cc_number":"4012888818888", "cc_expiration":"022019", "cc_cid":"318", "first_name":"John", "last_name":"Smith", "address1":"4300 E Pacific Coast Hwy", "address2":"Suite 1", "city":"Los Angeles", "state":"CA", "zip":"90804", "country_code":"USA", "phone":"15162065574"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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":"022019",
    "cc_number":"8888",
    "city":"Long Beach",
    "country_code":"USA",
    "first_name":"John",
    "last_name":"Smith",
    "phone":"15162065574",
    "state":"CA",
    "type":"visa",
    "zip": "90804"
}

This request will register the billing method for a customer.

/partners/{partner_sid}/billing_method

Required Scopes

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

Path Arguments

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

Body Arguments

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

Required fields to create a billing method are:

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

Get Billing Method by Partner SID

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.

GET /partners/{partner_sid}/billing_method

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Delete Billing Method

The following DELETE request deletes a billing method associated with the targeted partner secure ID.

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

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.

DELETE /partners/{partner_sid}/billing_method

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

Required Scopes

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

Path Arguments

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

Phone Numbers

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

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

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

Short codes are short phone numbers used for SMS communications.

DID Object

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

Sample DID object:

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
    "in_country_format": "(516) 206-5575",
    "international_format": "+1 516-206-5575",
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}
Attribute Data Type Description
attributes create update object The DID attributes.
callback_url create update string The callback URL to receive events for SMS.
capabilities read only integer This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability:
  • 1 for 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 read only string The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
did_group_sid create update string The DID group secure ID.
did_sid read only string The DID secure ID.
in_country_format read only string The DID in a national format.
international_format read only string The DID in an international format.
locality read only string The locality or city of the DID.
lrn_sid read only string The secure ID of the Location Routing Number, which this DID belongs to.
name create update string The DID name. The default value is N/A.
partner_sid read only string The secure ID of the partner associated with the DID.
phonenumber create string The phone number for the DID in E.164 format.
price read only number The price of the DID.
state read only string The state or province of the DID.
string_key_1 create update string User defined string key.
string_key_2 create update string User defined string key.
transformations create update array of objects The transformations that are applied to the DID. Refer to the transformations section for more information.
trunk_group_sid create update string The secure ID of the trunk group associated with the DID.

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

This request assigns a DID to a partner.

/phonenumber/dids

Required Scopes

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

Body Arguments

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

A valid and available phonenumber is required to rent a DID.

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

Get DIDs

The following GET request returns rented DIDs matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of DID objects.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "country_code": "USA",
            "did_group_sid": null,
            "did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe",
            "in_country_format": "(516) 206-5574",
            "international_format": "+1 516-206-5574",
            "locality": "NEW YORK",
            "lrn_sid": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "phonenumber": "15162065574",
            "price": "0.6",
            "state": "NY",
            "string_key_1": null,
            "string_key_2": null,
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/dids?limit=1&offset=1"
    },
    "total": 2
}

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

GET /phonenumber/dids

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

Required Scopes

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

Query Arguments

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

Get DID by SID

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 serialized copy of the DID object.

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

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

GET /phonenumber/dids/{did_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Query Arguments

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

Update DID

The following PATCH request updates the DID object, targeted by secure ID, with the values in the request body.

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

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

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

This request updates a DID, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete DID

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

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, targeted by secure ID, from a partner account.

DELETE /phonenumber/dids/{did_sid}

Required Scopes

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

Path Arguments

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

Browse Available DIDs

The following GET request returns available DIDs matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of available DID objects.

{
    "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",
            "lrn_sid": null,
            "name": "N/A",
            "partner_sid": null,
            "phonenumber": "15162065573",
            "price": "0.6",
            "state": "NY",
            "string_key_1": null,
            "string_key_2": null,
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1&offset=1"
    },
    "total": null
}

This request returns a pool of rentable phone numbers.

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

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

Required Scopes

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

Get Available DID by SID

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

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids/07e3dee3-2f0d-4254-b635-21334ccde8b9' \
-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": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
    "in_country_format": "(516) 206-5573",
    "international_format": "+1 516-206-5573",
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": null,
    "phonenumber": "15162065573",
    "price": "0.6",
    "state": "NY",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request returns data for a rentable phone number, targeted by secure ID.

GET /phonenumber/available_dids/{did_sid}

This request is enabled for Field Filtering.

Required Scopes

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

DID Emergency Object

This section goes over the parts of the DID 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)

Sample 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"
        }
    ]
}
Attribute Data Type Description
caller_name update string The name that will appear on receiving party phones.
enabled update 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 update 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

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

Get DID Emergency

The following GET request returns DID Emergency object for the DID, targeted by secure ID.

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 data for DID emergency, targeted by the DID secure ID.

GET /phonenumber/dids/{did_sid}/emergency

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

Required Scopes

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

Path Arguments

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

Update DID Emergency

The following PATCH request updates the DID Emergency object, targeted by the DID secure ID, with the values in the request body.

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

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

This request updates a DID emergency, targeted by the DID secure ID.

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

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

Required Scopes

To update a DID Emergency object, the partner must have the following scope enabled:

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

All fields can be updated.

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

Delete DID Emergency

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

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 from a specific DID.

DELETE /phonenumber/dids/{did_sid}/emergency

Required Scopes

To delete a DID Emergency object, the partner must have the following scope enabled:

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.

Sample DID Line Information object:

{
    "caller_name": "John Smith",
    "class_of_service": "business",
    "enabled": true,
    "extended_business_name": "J Smith Carpenter",
    "extended_first_name": "John",
    "extended_last_name": "Smith",
    "privacy": "public",
    "screening": "allow_all"
}
Attribute Data Type Description
caller_name update string The name that will appear on receiving party phones.
class_of_service update string The type of establishment that the service is for. Values accepted in this field are:
  • business
  • none
  • residential
The default value is none.
enabled update 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 update string The business name associated with the caller. This extended information is given according to the provider and phone device.
extended_first_name update string The first name of the caller. This extended information is given according to the provider and phone device.
extended_last_name update string The last name of the caller. This extended information is given according to the provider and phone device.
privacy update string Either public or private. This is whether or not the caller name will be displayed. The default is public.
screening update string Determines what types of calls are accepted. Values accepted in this field are:
  • allow_all to allow all calls.
  • block_collect to block collect calls.
  • block_third_number to block third number (operator assisted) calls.
  • block_third_number_collect to block third number (operator assisted) and collect calls.
The default value is block_third_number_collect.

Get DID Line Information

The following GET request returns DID Line Information object for the DID, targeted by secure ID.

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.

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

This request returns data for DID line information.

GET /phonenumber/dids/{did_sid}/line_information

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

Required Scopes

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

Path Arguments

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

Update DID Line Information

The following PATCH request updates the DID Line Information object, targeted by the DID secure ID, with the values in the request body.

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

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

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

This request updates a DID line information, targeted by the DID secure ID.

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

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

Required Scopes

To update a DID Line Information object, the partner must have the following scope enabled:

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

All fields can be updated.

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

Delete DID Line Information

The following DELETE request deletes a DID line information, targeted by the DID secure ID.

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 from a specific DID.

DELETE /phonenumber/dids/{did_sid}/line_information

Required Scopes

To delete a DID Line Information object, the partner must have the following scope enabled:

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.

Sample DID Group object:

{
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
Attribute Data Type Description
did_group_sid read only string The DID group secure ID.
name create update string The name of the DID group.
partner_sid read only string The partner secure ID.

Create DID Group

The following POST request creates a 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",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

This request creates a DID group.

/phonenumber/did_groups

Required Scopes

To create a DID Group object, the partner must have the following scope enabled:

Body Arguments

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

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

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

Get DID Groups

The following GET request returns DID groups matching the criteria in the request URL.

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 list of DID Group objects.

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

This request returns a list of DID groups.

GET /phonenumber/did_groups

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

Required Scopes

To get information about DID Group objects, the partner must have the following scope enabled:

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",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

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

GET /phonenumber/did_groups/{did_group_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a DID Group object, the partner must have the following scope enabled:

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 the DID Group object, targeted by secure ID, with the values in the request body.

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 updated DID Group object.

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

This request updates a DID group, targeted by secure ID.

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

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

Required Scopes

To update a DID group object, the partner must have the following scope enabled:

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

The field that can be updated is name.

Refer to this table to view all fields that appear in 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'

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

This request deletes a DID group, targeted by secure ID.

DELETE /phonenumber/did_groups/{did_group_sid}

Required Scopes

To delete a DID Group object, the partner must have the following scope enabled:

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.

Sample Prefix object:

{
    "attributes": {},
    "callback_url": null,
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}
Attribute Data Type Description
attributes create update object The prefix attributes.
callback_url create update string The callback URL.
lrn_sid read only string The secure ID of the Location Routing Number, which this prefix belongs to.
name create update string The prefix name. The default value is N/A.
partner_sid create update string The partner secure ID.
prefix create update string The prefix that will enable routing logic.
prefix_sid read only string The prefix secure ID.
source_trunk_group_sid read only string The prefix source trunk group secure ID.
string_key_1 create update string User defined string key.
string_key_2 create update string User defined string key.
transformations create update array The prefix transformations.
trunk_group_sid create update 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,
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request creates a Prefix object.

/phonenumber/prefixes

Required Scopes

To create a Prefix object, the partner must have the following scope enabled:

Body Arguments

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

A required field to create a prefix is prefix.

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

Get Prefixes

The following GET request returns prefixes matching the criteria in the request URL.

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 list of Prefix objects.

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

This request returns a list of Prefix objects.

GET /phonenumber/prefixes

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

Required Scopes

To get information about Prefix objects, the partner must have the following scope enabled:

Query Arguments

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

Get Prefix by SID

The following GET request returns a prefix, 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,
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "prefix": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

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

GET /phonenumber/prefixes/{prefix_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Prefix object, the partner must have the following scope enabled:

Path Arguments

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

Query Arguments

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

Update Prefix

The following PATCH request updates the Prefix object, targeted by secure ID, with the values in the request body.

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 updated Prefix object.

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

This request updates a prefix, targeted by secure ID.

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

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

Required Scopes

To update a Prefix object, the partner must have the following scope enabled:

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

Refer to this table to view all fields that appear in 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'

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

This request deletes a prefix, targeted by secure ID.

DELETE /phonenumber/prefixes/{prefix_sid}

Required Scopes

To delete a Prefix object, the partner must have the following scope enabled:

Path Arguments

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

Rate DID Object

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

Sample Rate DID object:

{
    "country_code": null,
    "country_name": null,
    "prefix": null,
    "price": "0.6"
}
Attribute Data Type Description
country_code read only string The ISO 3166-1 alpha-3 code of this rate.
country_name read only string The country name of this rate.
prefix read only string The number prefix for the DID.
price read only number The price for this rate.

Get Rates

The following GET request returns phone number rates matching the criteria in the request URL.

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.

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

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

Required Scopes

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

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.

GET /phonenumber/rates/{phonenumber}

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

Required Scopes

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

Path Arguments

Parameter Data Type Description
phonenumber required string The phone number.

Download CSV with Rates

The following GET request returns rates in CSV format.

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/rates/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 with all phone number rates.

GET /phonenumber/rates/csv

This request is enabled for Field Filtering.

Required Scopes

To get a CSV with the rates the partner must have one of the following scopes enabled:

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.

Sample Short Code object:

{
    "attributes": {},
    "callback_url": null,
    "country_code": "USA",
    "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562",
    "locality": null,
    "lrn_sid": null,
    "name": "test",
    "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417",
    "short_code": "26399",
    "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc",
    "state": "IL",
    "string_key_1": null,
    "string_key_2": null
}
Attribute Data Type Description
attributes update object The attributes of the short code.
callback_url update string The callback URL.
country_code update string The country of the short code.
did_group_sid update string The short code secure ID.
locality update string The region of the short code.
lrn_sid read only string The secure ID of the Location Routing Number, which this short code belongs to.
name update string The short code name.
partner_sid update string The partner secure ID.
short_code update string The short code.
short_code_sid read only string The short code secure ID.
state update string The state of the short code.
string_key_1 update string User defined string key.
string_key_2 update string User defined string key.

Get Short Codes

The following GET request returns short codes matching the criteria in the request URL.

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 list of Short Code objects.

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

This request returns a list of Short Code objects.

GET /phonenumber/short_codes

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

Required Scopes

To get information about Short Code objects, the partner must have the following scope enabled:

Query Arguments

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

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,
    "lrn_sid": null,
    "name": "test",
    "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417",
    "short_code": "26399",
    "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc",
    "state": "IL",
    "string_key_1": null,
    "string_key_2": null
}

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

GET /phonenumber/short_codes/{short_code_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about a Short Code object, the partner must have the following scope enabled:

Path Arguments

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

Query Arguments

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

Update Short Code

The following PATCH request updates the Short Code object, targeted by secure ID, with the values in the request body.

curl -X PATCH \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
-H 'Content-Type: application/json' \
--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 updated Short Code object.

{
    "attributes": {},
    "callback_url": null,
    "country_code": "USA",
    "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562",
    "locality": null,
    "lrn_sid": 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",
    "string_key_1": null,
    "string_key_2": null
}

This request updates a short code, targeted by secure ID.

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

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

Required Scopes

To update a Short Code object, the partner must have the following scope enabled:

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete Short Code

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

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.

DELETE /phonenumber/short_codes/{short_code_sid}

Required Scopes

To delete a Short Code object, the partner must have the following scope enabled:

Path Arguments

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

Browse Coverage

The following GET request returns data about available phone numbers matching the criteria in the request URL.

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

GET /phonenumber/coverage

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

Required Scopes

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

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
  • locality
  • npa
  • npa_nxx
  • state
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.

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.

Sample Application object:

{
    "apns_id": "",
    "apns_p12": null,
    "apns_p12_password": null,
    "apns_topic": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": "",
    "google_key": "",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
Attribute Data Type Description
apns_id create update string The Apple Push Messaging Application ID.
apns_p12 create update string The Apple Push Notification P12 certificate, encoded to Base64.
apns_p12_password create update string The passphrase of the Apple Push Notification P12 certificate.
apns_topic create update string The default Apple Push Notification topic for the application.
application_sid read only string The application secure ID.
google_id create update string The Google Push Messaging Application ID.
google_key create update string The Google Push Messaging authentication key.
name create update string The name of the application.
partner_sid read only 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.

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

This request will add an application for sending out push notifications.

/push/applications

Required Scopes

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

Body Arguments

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

No fields are required to create an application, an empty object can be passed.

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

Get Applications

The following GET request returns applications matching the criteria in the request URL.

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 list of Application objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "apns_id": null,
            "apns_p12": null,
            "apns_p12_password": null,
            "apns_topic": 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.

GET /push/applications

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

Required Scopes

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

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,
    "apns_topic": 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 for an application, targeted by secure ID.

GET /push/applications/{application_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Application

The following PATCH request updates the Application object, targeted by secure ID, with the values in the request body.

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 updated Application object.

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

This request updates an application, targeted by secure ID.

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

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

Required Scopes

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

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 modified are:

Refer to this table to view all fields that appear in 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.

DELETE /push/applications/{application_sid}

Required Scopes

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

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.

Sample Device object:

{
    "application_sid": "b3edc875-f73c-4c48-895a-8697b92b8d07",
    "application_version": "",
    "device_sid": "56d485ae-0693-421a-91eb-6b02b152573a",
    "environment": "production",
    "os_version": "",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "token": "1111",
    "type": "ios"
}
Attribute Data Type Description
application_sid create string The application secure ID installed on the device.
application_version read only string The version of the application on the device.
device_sid read only string The device secure ID.
environment read only 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 read only string The device operating system version.
partner_sid read only string The partner secure ID.
token create update string The Push Notification identifying token from Google or Apple.
type create update string The type of the device operating system. Values accepted in this field are ios 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.

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

This request creates a device for sending out push notifications.

/push/devices

Required Scopes

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

Query Arguments

Parameter Data Type Description
reuse boolean Whether the system will search for an existing device with the same parameters (i.e., token, type and environment).
  • When set to true and such a device exists, the Device object with this device_sid will be returned.
  • When set to false and a device with the same parameters exists, a new device will still be created.
The default value is true.

Body Arguments

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

Required fields to create a device are:

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

Get Devices

The following GET request returns devices matching the criteria in the request URL.

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 list of Device objects.

{
    "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 devices used for push notifications.

GET /push/devices

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

Required Scopes

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

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 for a device, targeted by secure ID.

GET /push/devices/{device_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Device

The following PATCH request updates the Device object, targeted by secure ID, with the values in the request body.

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

This request updates a device, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

Refer to this table to view all fields that appear in the 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.

DELETE /push/devices/{device_sid}

Required Scopes

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

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.

Attribute Data Type Description
android_click_action create string The action when a user clicks on the notification.
android_icon create string The notification icon.
android_sound create string The sound file that is included in an app that will play instead of the default device notification sound.
android_tag create string Indicates whether each notification message results in a new entry on the notification center on Android.
body create string The notification body text.
collapseKey create string Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.
data create object A custom data object that is passed back to the application.
ios_badge create integer The badge on the client app home icon.
ios_category create string The category APS payload.
ios_collapse_id create 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 create integer The mutable-content APS payload.
ios_sound create string The sound file that is included in an app that will play instead of the default device notification sound.
ios_topic create string The topic APS payload.
notification_sid read only string The notification secure ID.
partner_sid read only string The secure ID of the partner associated with the message.
priority create string The delivery priority for the notification. Values accepted in this field are: very_low, low, normal, high, and very_high.
recipients create array The list of devices secure IDs which will receive the notification.
title create string The notification title.
ttl create 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.

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

This request will send a push notification to one or more devices.

/push/notifications

Recipients of the push notifications are added to the recipients array.

Required Scopes

To send a notification the partner must have one of the following scopes enabled:

Body Arguments

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

A required field to create a Notification object is recipients.

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

Rating

The Rating API allows the partners to get the rates that will be applied when calling the phone number or sending text messages to them from CarrierX rented DIDs. You can either get the rates used with CarrierX DIDs in general, or rates for specific DIDs (voice or messages) or endpoints (voice calls only).

Rating Call Response Object

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

Sample Rating Call Response object

{
    "duration_billing": "60",
    "price": "0.01400",
    "rate": "0.01400"
}
Attribute Data Type Description
duration_billing read only number The duration of the call in seconds used for billing.
price read only number The total price of the call.
rate read only number The call rate used to calculate the call total price.

Get Call Rate

The following GET request returns rates for voice calls to the phone number specified in the request.

curl -X GET \
'https://api.carrierx.com/core/v2/rating/voice_calls?to=17605692222&duration=10' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "duration_billing": "60",
    "price": "0.01400",
    "rate": "0.01400"
}

This request returns the voice call rates for the destination phone number specified in the request.

GET /rating/voice_calls

Required Scopes

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

Query Arguments

Parameter Data Type Description
did_sid string The secure ID of the DID used for the call, for which you want to know the rates.
duration required integer The duration of the call in seconds that will be used to calculate the call price. If the duration is less than the multiple of the duration_billing, it will be rounded up to the nearest multiple of the duration_billing for the price calculation.
endpoint_sid string The endpoint secure ID used for the call, for which you want to know the rates.
to required string The destination phone number.

Rating Messages Response Object

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

Sample Rating Messages Response object

{
    "price_max": "0.01000",
    "price_min": "0.01000",
    "rate_max": "0.01000",
    "rate_min": "0.01000",
    "segments": "1"
}
Attribute Data Type Description
price_max read only number The maximum price of the message depending on the maximum message segment rate and segments number.
price_min read only number The minimum price of the message depending on the maximum message segment rate and segments number.
rate_max read only number The maximum rate for the message segment depending on the MCC/MNC used to send the message.
rate_min read only number The minimum rate for the message segment depending on the MCC/MNC used to send the message.
segments read only number The number of the message segments used to calculate the total message price.

Get Messages Rate

The following GET request returns rates for messages sent to the phone number specified in the request.

curl -X GET \
'https://api.carrierx.com/core/v2/rating/sms_messages?to=17605692222&segments=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "price_max": "0.01000",
    "price_min": "0.01000",
    "rate_max": "0.01000",
    "rate_min": "0.01000",
    "segments": "1"
}

This request returns the messages rates for the destination phone number specified in the request.

GET /rating/sms_messages

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

Query Arguments

Parameter Data Type Description
did_sid string The secure ID of the DID used to send the messages, for which you want to know the rates.
segments required integer The number of the message segments that will be used to calculate the total message price.
to required string The destination phone number.

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.

Sample 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
}
Attribute Data Type Description
domain_name create update string The unique domain name.
domain_sid read only string The domain secure ID.
expired_mode create update string Determines whether to redirect or serve page contents directly if the link is expired. Values accepted in this field are:
  • proxy_pass to serve the contents of the page directly.
  • redirect_permanent to return the permanent redirect status code before redirect.
  • redirect_temporary to return the temporary redirect status code before redirect.
The default value is redirect_temporary.
expired_page create update string The content to serve when a link is expired.
expired_status_code create update integer The status code to be returned if the expired_mode value is proxy_pass. Values accepted in this field are:
  • 2xx to return one of the success status codes.
  • 4xx to return one of the client error status codes.
  • 5xx to return one of the server error status codes.
minimum_length create update integer The shortest link that the system will create.
not_found_mode create update string Determines whether to redirect or serve page contents directly if the link is not found. Values accepted in this field are:
  • proxy_pass to serve the contents of the page directly.
  • redirect_permanent to return the permanent redirect status code before redirect.
  • redirect_temporary to return the temporary redirect status code before redirect.
The default value is redirect_temporary.
not_found_page create update string The content to serve when a link is not found.
not_found_status_code create update integer The status code to be returned if the not_found_mode value is proxy_pass. Values accepted in this field are:
  • 2xx to return one of the success status codes.
  • 4xx to return one of the client error status codes.
  • 5xx to return one of the server error status codes.
partner_sid create update string The secure ID of the partner associated with the domain.
scope create update string Determines who can create a link using the domain_sid . Values accepted in this field are:
  • children to allow sub-partners to create links with the domain.
  • public to allow all partners to create links with the domain.
  • self to allow only the partner who has created the domain to create links with this domain.
The default value is children.
secure create update string Determines whether links returned should be prefixed with https. Values accepted in this field are:
  • disabled to use the insecure http prefix with the domain name.
  • optional to allow using both http and https prefixes with the domain name.
  • required to use only secure https prefix with the domain name.
The default value for this field is disabled.
suffix_pattern create update 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 Domain object.

/shortener/domains

Required Scopes

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

To set the expired_status_code and not_found_mode fields value to proxy_pass, the partner must additionally have the shortener.allow_domain_mode_proxypass scope enabled.

To set the secure field value to required, the partner must additionally have the shortener.allow_domain_secure_required scope enabled.

Body Arguments

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

A required field to create a domain is domain_name.

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

Get Domains

The following GET request returns domains matching the criteria in the request URL.

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 list of Domain objects.

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

GET /shortener/domains

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

Required Scopes

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

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 returns data for a domain, targeted by secure ID.

GET /shortener/domains/{domain_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Domain

The following PATCH request updates the Domain object, targeted by secure ID, with the values in the request body.

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

This request updates a domain, targeted by secure ID.

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

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

Required Scopes

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

To set the expired_status_code and not_found_mode fields value to proxy_pass, the partner must additionally have the shortener.allow_domain_mode_proxypass scope enabled.

To set the secure field value to required, the partner must additionally have the shortener.allow_domain_secure_required scope enabled.

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 modified are:

Refer to this table to view all fields that appear in 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.

DELETE /shortener/domains/{domain_sid}

Required Scopes

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

Path Arguments

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

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

Sample 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"
}
Attribute Data Type Description
date_accessed read only string The date when the link was accessed.
date_created read only string The date when the link was created.
destination_url create update string The site where the user will be sent.
domain_sid create update string The domain secure ID.
hits read only integer The number of times that the link has been hit.
link_sid read only string The link secure ID.
maximum_ttl create update integer The link lifetime in seconds. Entering the -1 value means that the link will not expire.
mode create update string The mode of the link. Values accepted in this field are:
  • proxy_pass to serve the contents of the page directly.
  • redirect_permanent to return the permanent redirect status code before redirect.
  • redirect_temporary to return the temporary redirect status code before redirect.
The default value is redirect_temporary.
partner_sid read only string The partner secure ID.
short_name create update 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 read only string The URL to get access to destination_url. This field value is generated automatically.

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

/shortener/links

Required Scopes

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

To set the mode field value to proxy_pass, the partner must additionally have the shortener.allow_link_mode_proxypass scope enabled.

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

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

Required fields to create a link are:

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

The following GET request returns links matching the criteria in the request URL.

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 list of Link objects.

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

GET /shortener/links

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

Required Scopes

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

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 data for a link, targeted by secure ID.

GET /shortener/links/{link_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

The following PATCH request updates the Link object, targeted by secure ID, with the values in the request body.

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

This request updates a link, targeted by secure ID.

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

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

Required Scopes

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

To set the mode field value to proxy_pass, the partner must additionally have the shortener.allow_link_mode_proxypass scope enabled.

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 modified are:

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

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.

DELETE /shortener/links/{link_sid}

Required Scopes

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

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.

Sample 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"
}
Attribute Data Type Description
date_created read only string The date when the message was created.
date_status_changed read only string The date when the message status last changed.
direction read only string The direction of the message. Values accepted in this field are inbound for incoming messages and outbound for outgoing messages.
from_did create string The phone number that the message will be from, in E.164 format.
mcc read only integer The mobile country code.
media_urls create array The list of URLs for media resources, if type of message is set to mms.
message create string The message body.
message_segments read only integer The quantity of 160-symbols segments of an sms message. Messages with type set to mms always consist of a single segment.
message_sid read only string The message secure ID.
mnc read only integer The mobile network code.
partner_sid read only string The secure ID of the partner this message belongs to.
price read only string The price in US dollars determined for the message to be delivered.
status read only 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 create string The phone number that the message will be delivered to, in E.164 format.
type create 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.

/sms/messages

Required Scopes

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

Body Arguments

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

Required fields to send a message are:

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

Get SMS Messages

The following GET request returns messages matching the criteria in the request URL.

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 list of SMS objects.

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

GET /sms/messages

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

Required Scopes

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

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 for a message, targeted by secure ID.

GET /sms/messages/{message_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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.

Sample 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
}
Attribute Data Type Description
date_insert read only string Date when the detail record was inserted to the database.
date_sent read only string Date when the message was actually sent.
date_start read only string Date and time of the message creation.
date_stop read only string Date and time of the message delivering (with any status).
delay_sent read only integer Delay between when the request is received and the message is actually sent measured in seconds.
direction read only string The direction of the message. Values accepted in this field are inbound for incoming messages and outbound for outgoing messages.
dr_sid read only string Secure ID of the message detail record.
mcc read only integer The mobile country code.
media_urls read only array The list of URLs for media resources, if type of message is set to mms.
message read only string The message body.
message_segments read only integer The quantity of 160-symbols segments of an sms message. Messages with type set to mms always consist of a single segment.
mnc read only integer The mobile network code.
number_billing read only 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 read only string The destination number in E.164 format.
number_external read only 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 read only string The source number in E.164 format.
partner_sid read only string The secure ID of the partner this message belongs to.
price read only number The price in US dollars determined for the message to be delivered.
provider read only string Provider that is used to send the message.
status read only 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 read only string The type of message. Values accepted in this field are mms and sms.
version read only 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 matching the criteria in the request URL.

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 list of SMS Detail Records objects.

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

GET /sms/message_drs

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

Required Scopes

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

To view information about SMS Detail Records objects for the inherited partners, the partner must additionally have the sms.read_descendant scope enabled.

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 for an SMS/MMS message, targeted by the message detail record secure ID.

GET /sms/message_drs/{dr_sid}

This request is enabled for Field Filtering.

Required Scopes

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

To view information about an SMS Detail Records object for the inherited partners, the partner must additionally have the sms.read_descendant scope enabled.

Path Arguments

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

Rate Object

Sample Rate object:

{
    "country_code": "CZE",
    "country_name": "Czech Republic",
    "mcc": 230,
    "mnc": 4,
    "network": null,
    "operator": null,
    "price": "0.08533"
}
Attribute Data Type Description
country_code read only string The ISO 3166-1 alpha-3 three-letter country code of this rate.
country_name read only string The common name of the country of this rate.
mcc read only integer Mobile country code for this rate.
mnc read only integer Mobile network code for this rate.
network read only string The name of the network used for this rate.
operator read only string The name of the operator used for this rate.
price read only 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.

GET /sms/rates/outbound/{sub_type}

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

Required Scopes

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

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.

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

This request is enabled for Result Filtering and Field Filtering.

Required Scopes

To get a list of outbound rates for a partner in CSV format the partner must have one of the following scopes enabled:

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.

The containers can be associated with the Conference, Conference Playback, FlexML, and Voicemail endpoints, and the files can be accessed by the applications used with these endpoints.

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.

Sample 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
}
Attribute Data Type Description
allow_publish create update boolean Whether or not the files in the container can be published.
allowed_classifications create update 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 read only integer The percentage of bytes available.
available_files_percent read only integer The percentage of files available.
blocked_classifications create update 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 read only string The container secure ID.
durability_class read only string How the data is stored. At this time, only the default unassigned value is available.
encrypted create 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 create update integer A user-defined integer key.
integer_key_2 create update integer A user-defined integer key.
name create update string The container name.
parent_container_sid create update string The parent container secure ID. If set, and referenced file no longer exists, the container will be deleted.
partner_sid create update string The secure ID of the partner associated with the container.
publish_domain create update string The domain URL that will be used to publish the files.
quota_bytes create update integer The maximum number of bytes that can be stored in the container.
quota_files create update integer The maximum number of files that can be stored in the container.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
total_bytes read only integer The total size of files in bytes that are stored in the container.
total_files read only integer The total number of files that are stored in the container.
unique create 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.

/storage/containers

Required Scopes

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

Body Arguments

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

No fields are required to create a container, an empty object can be passed.

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

Get Containers

The following GET request returns containers matching the criteria in the request URL.

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 list of Container objects.

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

GET /storage/containers

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

Required Scopes

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

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 data for a container, targeted by secure ID.

GET /storage/containers/{container_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments

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

Update Container

The following PATCH request updates the Container object, targeted by secure ID, with the values in the request body.

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

This request updates a container, targeted by secure ID.

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

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

Required Scopes

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

To modify the publish_domain attribute value for the storage container, the partner must additionally have the storage.allow_container_publish_domain_update scope enabled.

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 modified are:

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

Delete Container

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

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.

DELETE /storage/containers/{container_sid}

Required Scopes

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

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.

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