Core API Reference

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

Using the REST API

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

Using Postman

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

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

Run in Postman

Main Conventions

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

create The attribute can be set when the user creates the object using the POST method.
update The attribute can be modified when the user updates the object using either PATCH or PUT methods.
read only The attribute is set by the system and the user can neither set nor modify it.

Authentication

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

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

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

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

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

Currently, CarrierX API requests use two types of authentication:

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

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

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

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

Requests

Sample request to create Conference endpoint

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

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

A simplest request will have the following structure:

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

Other request may have additional structure elements which include:

Request URL

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

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

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

Request Methods

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

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

POST

Sample POST request that creates a trunk

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

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

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

GET

Sample GET request that returns the currently logged-in partner

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

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

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

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

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

PATCH/PUT

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DELETE

Sample DELETE request that deletes an endpoint

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

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

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

Rate Limiting

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

Responses

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

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

HTTP Status Codes

Typical 200 status code in the response

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

The Core API uses the following HTTP status codes:

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

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

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

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

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

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

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

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}
Error Code Message Description
2xx Success  
200 OK The request has succeeded. The result will be a returned JSON object or a link to download a file.
201 Created The request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files.
204 No Content The server has successfully fulfilled the request. There is no additional content to send in the response payload body. This response code is normally returned to the DELETE requests.
4xx Client Errors  
400 Bad Request The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
400 No JSON object could be decoded Generally an indicator that there is a syntax error.
401 Bad credentials The request requires correct user authentication.
401 Unauthorized The request requires user authentication.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404 Cannot find item by SID The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire.
404 Not Found The requested resource was not found on the server.
409 Depends on the conflict source This status code (aka Conflict) means that your request could not be processed because of some conflict that has occurred during such a request. For specific details see the error section of the API method that you are calling. As a rule, you can try to resolve the conflict by resubmitting your request later.
415 Unsupported media type Ensure that the header includes support for the JSON content type.
422 Object validation error The server cannot process a request to the API because the request contains semantic errors or does not meet certain conditions.
5xx Server Errors  
500 Internal server error The server encountered an unexpected condition which prevented it from fulfilling the request.

Response Objects

Typical formatted JSON object in the response

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

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

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

With jq, the request will look like this:

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

Pagination

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

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

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

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

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

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

The pagination parameters include:

limit

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

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

order

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

offset

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

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

after/ before

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

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

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

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

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

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

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

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

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

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

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

Pagination Response

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

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

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing the 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 added to the query URL to restrict or customize the results of a JSON response by certain parameters (e.g., name, capabilities, state, country_code, etc.). The common rule is that, with some exceptions, you can filter those results by any top-level field(s) that are returned in the response. Moreover, in some cases you can use the nested subfields for result filtering. In this case you need to use a dot in the filter name to separate the parent field and the nested subfield, e.g. trunks.allow_transfer eq false or properties.login eq username.

The structure of result filtering is as follows: filter=object_attribute filter_operator value. You can also use the and operator to combine several filters for more specific searches. For example, for a DID object we could apply the following filter: filter=state eq "NY" and phonenumber like "%555%".

Filter values can also be put inside single or double quotes. This is not necessary when the filter value is just a single word like USA. However, if your filter value consists of more than one word, the quotes are required. For example, name eq "filter value name".

Result Filtering Quick Reference

Operator Definition Example Description
bit Bit mask: this operator is used with the capabilities and active_capabilities fields only. It may have the following core values: 1 = SMS IN (1 represents 1 in a bit mask), 2 = SMS OUT (2 represents 10 in a bit mask), 4 = VOICE (4 represents 100 in a bit mask), 8 = MMS IN (8 represents 1000 in a bit mask), 16 = MMS OUT (16 represents 10000 in a bit mask). You can use this operator to look for all the DIDs that have a particular capability alongside with other possible capabilities those DIDs may have. For example capabilities bit 4 returns all the available DIDs with the following capabilities: 4(100) and up, whatever other capabilities it may have (if any), e.g. 4+1=5(101), 4+2=6(110), 4+1+2=7(111), 4+8=12(1100), 4+1+8=13(1101), etc. capabilities bit 3

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

Field Filtering

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

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

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

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

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

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

include_fields and exclude_fields accept comma-separated strings as values.

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

Core Concepts

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

Batch Operations

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

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

Callbacks

The CarrierX API enables callbacks to be sent to a URL. The callbacks are triggered when a specific action occurs, such as when either sending or receiving an SMS, calling into a conference, etc. 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, you can set the following callbacks

On the DID object, set the value of the callback_url field for the callbacks related to SMS activity.

sms and callback_url Callback

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

{
    "date_changed":"2023-09-04T17:37:38.852Z",
    "date_created":"2023-09-04T17:37:36.123Z",
    "date_status_changed":"2023-09-04T17:37:00.000Z",
    "direction":"outbound",
    "from": "15162065319",
    "group_recipients":[],
    "mcc":250,
    "media_urls":[],
    "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": "15162065318",
    "type":"sms",
    "user_data":null}
}

The system sends sms and callback_url callbacks when an action related to an SMS event occurs.

Attribute Data Type Description
date_changed string The date and time when the message was last changed.
date_created string The date and time when the system created the message object.
date_status_changed string The date and time when the system changed the message status.
direction string The message direction.
from string The phone number which was used to send the message. Note, that legacy users may still see the old naming instead (from_did).
group_recipients array The list of phone numbers that an inbound or outbound mms group message is delivered to, in E.164 format
mcc integer The mobile country code that was used by the operator when sending the message.
media_urls array The list of URLs for media resources, if type of message is mms.
message string The message text. It can be empty when sending multimedia messages (MMS) or contain some text which was sent to the receiving party.
message_segments integer The number of segments which the message contains.
message_sid string The secure ID of the message which the system uses to identify the message among other messages.
mnc integer The mobile network code that was used by the operator when sending the message.
partner_sid string The secure ID of the partner associated with the message.
price number The message price. It is calculated as (the rate for the message) × (the number of the message segments).
status string The status of the message at the moment when the system sent the callback.
to string The phone number which was used to receive the message. Note, that legacy users may still see the old naming instead (to_did).
type string The type of message. Values returned in this field are mms and sms.
user_data string Some additional user-defined data added to the message.

app_mediator Callback

The app_mediator callback response

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

The app_mediator callback is triggered when a call is made to a Mediator binding or from a Mediator dialout.

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 integer 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 or the dialout_sid that was matched for the call.
type string The endpoint type.
version integer The API version.

app_conference_call Callback

The app_conference_call callback response

{
    "address_dst": "\\"15162065515\\" \\u003csip:15162065515@11.22.33.44\\u003e",
    "address_src": "\\"1234\\" \\u003csip:+17605692222@12.34.56.78",
    "bridge": "conference-bridge",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000001090",
    "custom_call_type": "foreign",
    "custom_name": "\\u00271234\\u0027",
    "date_disconnected": "2021-12-14T07:08:01.000Z",
    "date_insert": "2021-12-14T07:40:27.706Z",
    "date_join": "2021-12-14T07:07:31.000Z",
    "date_start": "2021-12-14T07:07:09.000Z",
    "date_stop": "2021-12-14T07:08:01.000Z",
    "direction": "inbound",
    "disconnect_cause": 16,
    "disconnect_originator": "src",
    "disconnect_reason": "Normal",
    "duration": 50,
    "duration_meeting": 30,
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
    "node": "11.22.33.44",
    "number_dst": "15162065515",
    "number_src": "+17605692222",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "role": "participant",
    "user_agent": "CX-IVS-SBC"
}

The app_conference_call callback is triggered when the calling party calls a phone number associated with the Conference endpoint.

Attribute Data Type Description
address_dst string The fully qualified address of the called party which includes the SIP information with special characters formatted.
address_src string The fully qualified address of the calling party which includes the SIP information with special characters formatted.
bridge string The name of the bridge which handled the call.
call_sid string The secure ID of the call which the system uses to identify it among other calls.
custom_call_type string The special field used to identify the origin of the call.
custom_name string The custom name for the calling party set by the software used, web, or IVR with special characters formatted.
date_disconnected string The date and time when the call was disconnected from the meeting.
date_insert string The date and time when the detail record about the call was inserted into the database.
date_join string The date and time when the calling party joined the meeting.
date_start string The date and time when the call started.
date_stop string The date and time when the call ended.
direction string The call direction, either inbound or outbound.
disconnect_cause integer The numeric SIP code used to describe the reason to drop the call.
disconnect_originator string The initiator of the disconnection.
disconnect_reason string The detailed descriptive information about the reason to drop the call.
duration number The total call duration, specified in seconds.
duration_meeting number The duration of the caller’s participation in the meeting, specified in seconds.
endpoint_sid string The secure ID of the Conference endpoint associated with the call.
meeting_room_sid string The secure ID of the meeting room with which the meeting is associated.
meeting_sid string The secure ID of the meeting in which the calling party participated.
node string The IP address of the bridge node.
number_dst string The called party phone number.
number_src string The calling party phone number.
partner_sid string The secure ID of the partner with which the Conference endpoint is associated.
role string The role of the calling party in the meeting.
user_agent string The details about the user agent used by the calling party, if available.

app_conference_meeting Callback

The app_conference_meeting callback response

{
    "attendee_count": 2,
    "audio_attendee_count": 2,
    "control_attendee_count": 0,
    "data_attendee_count": 0,
    "date_insert": "2021-12-14T07:40:33.843Z",
    "date_start": "2021-12-14T07:04:41.000Z",
    "date_stop": "2021-12-14T07:08:06.000Z",
    "duration": 205,
    "duration_audio": 205,
    "duration_control": 0,
    "duration_data": 0,
    "duration_meeting": 205,
    "duration_recording": 0,
    "duration_video": 0,
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "has_recording": false,
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "unique_attendee_count": 2,
    "video_attendee_count": 0
}

The app_conference_meeting callback is triggered when the calling party joins a Conference meeting.

Attribute Data Type Description
attendee_count integer The total number of the meeting attendees.
audio_attendee_count integer The number of the attendees which used audio conferencing during the meeting.
control_attendee_count integer The number of the attendees which used conference controls during the meeting.
data_attendee_count integer The number of the attendees which sent some data during the meeting.
date_insert string The date and time when the detail record about the meeting was inserted into the database.
date_start string The date and time when the meeting started.
date_stop string The date and time when the meeting ended.
duration number The total conference duration, measured in seconds.
duration_audio number The duration of the meeting audio conferencing, measured in seconds.
duration_control number The duration of the conference control usage during the meeting, measured in seconds.
duration_data number The duration of the meeting during which some data was sent or received (e.g., the participants used the screensharing feature), measured in seconds.
duration_meeting number The duration of the meeting, measured in seconds.
duration_recording number The duration of the meeting during which the recording was made, measured in seconds.
duration_video number The duration of the meeting during which the video conferencing was used, measured in seconds.
endpoint_sid string The secure ID of the Conference endpoint associated with the meeting.
has_recording boolean Whether or not the meeting was recorded.
meeting_room_sid string The secure ID of the meeting room associated with the meeting.
meeting_sid string The secure ID of the meeting which the system uses to identify it among other meetings.
partner_sid string The secure ID of the partner with which the Conference endpoint is associated.
unique_attendee_count integer The number of the unique attendees which took part in the meeting.
video_attendee_count integer The number of the attendees which used video conferencing during the meeting.

phonenumber_messaging_update Callback

The phonenumber_messaging_update callback response

{
    "did_sid":"d17a5391-1831-4d6b-adf0-5ba9a47ea6ad",
    "phonenumber":"13075220123",
    "messaging":{"enabled":true,"status":"enabled"}
}

The phonenumber_messaging_update callback is triggered when SMS/MMS messaging is enabled or disabled for a DID.

Attribute Data Type Description
did_sid string The secure ID of the rented DID.
phonenumber string The phone number for the rented DID in the E.164 format.
messaging string SMS/MMS messaging status for the rented DID. Consists of two parts:
  • the last enabled request, which was sent to enable or disable this DID. Possible values are true to enable and false to disable messaging for this DID.
  • the messaging status. Possible values are enabled, disabled, failed.

phonenumber_order Callback

The ` phonenumber_order` callback response

{
    "active_capabilities":4,
    "callback_url":"https://example.com/sms-callback-url",
    "campaign_sid": null, 
    "capabilities":7,
    "classification_sid":"d1a732b9-8530-499c-926a-e85282fc7387",
    "country_code":"CAN",
    "did_group_sid":null,
    "did_sid":"d713ea8a-c2ab-492f-85ac-83279ce4543e",
    "in_country_format":"(236) 804-0634",
    "international_format":"+1 236-804-0634",
    "locality":null,
    "lrn_sid":null,
    "name":"N/A",
    "partner_sid":"0a2015db-04dc-6fd1-8bd8-ebc2a815b58b",
    "phonenumber":"12368040634",
    "price":null,
    "state":null,
    "status":"assigned"
    "string_key_1":null,
    "string_key_2":null,
    "trunk_group_sid":null
}

The phonenumber_order callback is triggered when a DID from an external provider has been rented successfully.

Attribute Data Type Description
active_capabilities integer The rented DID active capabilities.
callback_url string The URL that receives callback messages in JSON format with data about a rented DID from an external provider.
capabilities integer The rented DID supported capabilities.
classification_sid string The rented DID classification secure ID.
country_code string The ISO 3166-1 alpha-3 code of the rented DID country.
did_group_sid string The secure ID of the rented DID group.
did_sid string The secure ID of the rented DID.
in_country_format string The rented DID in a national format.
international_format string The rented DID in an international format.
locality string The locality or city of the rented DID.
lrn_sid string The secure ID of the Location Routing Number assigned to this rented DID.
name string The DID name.
partner_sid string The secure ID of the partner associated with the rented DID.
phonenumber string The phone number for the rented DID in the E.164 format.
price number The price of the rented DID.
state string The state or province of the rented DID.
status string The current DID status. If the DID has been rented successfully, the status returned in this field should always be assigned. Otherwise, no callback will be sent.
string_key_1 string A user-defined string key.
string_key_2 string A user-defined string key.
trunk_group_sid string The secure ID of the trunk group associated with the rented DID.

Call Routing

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

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

Call Routing

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

Third-Party Routing

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

Transformations

Transformations look like the following

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

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

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

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

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

if_match

Sample if_match transformation

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

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

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

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

lookup_cic

Sample lookup_cic transformation

{
    "action": "lookup_cic",
    "direction": "inbound",
    "operands": [
        "false",
        "490",
        "{{src}}",
        "{{dst}}",
        "cic",
        "ignore",
        "e164",
        "guess"
    ]
}

The lookup_cic action is used to lookup the CIC (Carrier Identification Code) information for calls to toll-free phone numbers.

The action accepts eight operands: lookup_cic(force, lata, phonenumber_src, phonenumber_dst, destination, on_failure, input_format_src, input_format_dst)

Operand Data Type Description
force string Force lookup mode. Values accepted in this field are:
  • false to lookup only if the CIC information is empty.
  • true to always lookup the CIC, even if the cic field in the To header is already set.
The default value is false.
lata string LATA: Local Access and Transport Area, a geographic code representing the location of the call origination. Note, that this operand is required but it does not have a default value, therefore it must always be specified.
phonenumber_src string The call origination phone number. The default value is {{src}}.
phonenumber_dst string The destination toll-free phone number we are looking up the CIC for. The default value is {{dst}}.
destination string The destination field where the CIC will be stored. The default value is cic.
  • If this value is cic (default), the CIC will be stored in the cic field of the To header.
  • If set to some other custom value, the CIC will be stored in a custom header with a different name.
on_failure string The behavior on the transformation request failure. Values accepted in this field are:
  • die to reject the call with the 503 status code.
  • ignore to continue with the call passing the original cic value if it is present, but the system performed the lookup due to force operand set to true. If the cic value is missing, continue with the call but do not add cic attributes to it.
  • original_cic_or_die to pass the original cic value if it is present, but the system performed the lookup due to force operand set to true. Or reject the call with the 503 status code if the value is missing.
The default value is ignore.
input_format_src string The source number (phonenumber_src) input format. The transformation will try to determine if the number is domestic or international, and only perform a lookup if it looks like domestic. Values accepted in this field are:
  • e164 for the number to be considered domestic and perform a lookup if the number is 11 digits long and starts with 1. Otherwise, the phone number is considered international, and no lookup is performed.
  • guess for the number to be considered domestic and perform a lookup if the number starts with +1 and is 11 digits long. If the number does not start with +, but starts with 1 and is 11 digits long, then it is considered domestic, and a lookup is performed. If the number does not start with + and is 10 digits long, then the number type is set to guess and a lookup is performed. Otherwise, the phone number is considered international and no lookup is performed.
  • ignore_plus is used if the source may add extraneous + that should not be trusted. If the number is 11 digits long, and starts with 1, then the number is considered domestic and a lookup is performed. If the number is 10 digits long, then the number type is set to guess and a lookup is performed. Otherwise, the phone number is considered international and no lookup is performed.
The default value is guess.
input_format_dst string The destination number (phonenumber_dst) input format. Values in this field are similar to those of the input_format_src above.

lookup_cnam

Sample lookup_cnam transformation

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

The lookup_cnam action is used to lookup the CNAM information for the phone number.

The action accepts four operands: lookup_cnam(force, default, number, target)

Operand Data Type Description
force string Force lookup mode. Values accepted in this field are:
  • false to only lookup if the CNAM information is empty.
  • numeric that is similar to false, but also performs the lookup if the value matches the /^\+*\d+$/ regular expression (i.e., it looks like a phone number or an extension).
  • true to always lookup CNAM, even if the CNAM information is already filled.
The default value is true.
default string The default string to use if no CNAM information can be found. Values accepted in this field are: '', {{src}}, etc. The default value is ''.
number string The number to lookup. The default value is {{src}}.
target string The target where the result will be saved. If this value is set to or from, it should be written to the name portion of the appropriate field. Otherwise, if it is set to a custom header name, it may be equal to the entire value of a custom header. The default value is from.

lookup_rn

Sample lookup_rn transformation

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

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

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

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

reject

Sample reject transformation

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

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

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

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

Reject Reasons

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

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

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

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

rewrite_from

Sample rewrite_from transformation

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

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

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

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

rewrite_from_header_param

Sample rewrite_from_header_param transformation

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

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

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

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

rewrite_header

Sample rewrite_header transformation

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

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

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

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

rewrite_header_parameter

Sample rewrite_header_parameter transformation

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

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

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

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

rewrite_to

Sample rewrite_to transformation

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

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

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

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

rewrite_to_header_param

Sample rewrite_to_header_param transformation

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

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

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

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

set_header

Sample set_header transformation

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

The set_header action is used to add a new header.

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

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

set_header_parameter

Sample set_header_parameter transformation

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

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

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

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

set_user_data

Sample set_user_data transformation

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

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

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

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

sms_normalize

Sample sms_normalize transformation

{
    "action": "sms_normalize",
    "direction": "outbound",
    "operands": [
        "e164",
        "USA",
        "to",
        "ignore",
        "e164"
    ]
}

By default, all phone numbers for the SMS Object are always treated as E.164 international numbers.

The sms_normalize action is used to add a corresponding country prefix to the SMS Object from and/or to fields. This transformation is based on the Phonenumber Lookup object mechanism and the Phonenumber Lookup logic. With this transformation, for example, for all outbound messages you can indicate the country you need and by default all SMS messages with domestic number format in the to field will be routed to phone numbers inside that country, i.e. the system will be automatically converting such numbers to the E.164 format.

The action accepts five operands: sms_normalize(guess, country_code, field, on_failure, output_format)

Operand Data Type Description
guess string Tells the system to make a guess that the DID this transformation is applied to is either an E.164 or a domestic (in-country) number. This operand is activated if the country_code lookup step (see below) results in finding out that the corresponding DID matches both, an E.164 and a domestic phone number. Values accepted in this field are:
  • e164 in which case the system will try to make a guess that this DID is an international phone number and proceed further
  • in_country in which case the system will try to make a guess that the DID is a domestic number. In case of USA such number will be a part of NANP, the North American Numbering Plan.
The default value is e164. If the guess step does not bring any result, the system proceeds to the on_failure step.
country_code string The ISO 3166-1 alpha-3 code of the country.

To check, whether this number is a domestic (in-country) number, the system uses thecountry_code query parameter, to see if the number passed could be valid in the country specified in the request. This operand the system that before routing any outbound SMS or accepting any inbound SMS without the + prefix, it should first check such phone number and verify whether it is a valid number in that country.

If a valid number is found, the system adds the corresponding country code prefix to the phone number and the SMS is processed further (e.g. for the United Kingdom, the +44 prefix will be added), no further checks are made.

If no valid number is found, the system tries to find a match for this number among domestic (in-country) and E.164 numbers. Here, tree options are possible:
  • if a match is found and the number is only a valid domestic number or only a valid E.164 number, the SMS is processed further, no further checks are made.
  • if no match is found, the system switches to the on_failure step.
  • if the number matches both, domestic and E.164, the system switches to the guess step.
If thecountry_code query parameter is not set, the system uses country_code=USA by default.
field string The SMS Object field this transformation must be applied to. Valued accepted in this field are:
  • from
  • to (default)
on_failure string The behavior on the transformation request failure. Only one value is accepted in this field:
  • ignore to continue with the SMS sending/receiving.
output_format string The output format of the destination phone number. Only one value is accepted in this field:
  • e164 (default)

stir_validate

Sample stir_validate transformation

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

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

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

API Reference

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

Access Control

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

Access Control List Object

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

Sample Access Control List object

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

* Please note that for the Trunk Group and the Trunk Objects these fields are always null and read-only because Trunk Groups and Trunks are used for voice only.

Look Up Effective ACLs for Calls

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

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

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

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

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

GET /accesscontrol/effective_acl/calls

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

Required Scopes

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

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

Look Up Effective ACLs for SMS

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

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

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

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

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

GET /accesscontrol/effective_acl/sms

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

Required Scopes

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

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

Access Control Rule Object

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

Sample Access Control Rule object

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

Create Access Control Rule

/accesscontrol/rules
Creates an access control rule

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

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

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

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

/accesscontrol/rules
Required Scopes

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

Body Arguments

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

Required fields to create an access control rule are:

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

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

Get Access Control Rules

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

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

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

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

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

GET /accesscontrol/rules

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

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

Required Scopes

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

Get Access Control Rule by SID

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

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

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

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

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

GET /accesscontrol/rules/{rule_sid}

Returned ACRs apply to the partner and the parent partner.

This request is enabled for Field Filtering.

Required Scopes

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

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

Update Access Control Rule

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

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

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

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

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

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

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

Required Scopes

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

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

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete Access Control Rule

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

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

Response 204 status code with an empty body

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

DELETE /accesscontrol/rules/{rule_sid}

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

Required Scopes

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

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

Apps

The Apps API is used to display the detailed records of the calls made to the Conference and Mediator endpoints.

With Conference endpoints, the events associated with calling into the meeting trigger the creation of the App DR Conf CDR objects. When the calling party joins the meeting, this creates a related App DR Conf MDR object.

With Mediator endpoints, the events associated with the calls made to the bindings or from the dialouts trigger creation of the App DR Mediator objects. These detail records become available after the call is ended.

App DR Conf CDR Object

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

Sample App DR Conf CDR Object object

{
    "address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
    "address_src": "<sip:+17605692222@12.34.56.78",
    "audio_key": null,
    "bridge": "conference-bridge",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
    "custom_call_type": null,
    "custom_name": null,
    "date_disconnected": "2021-12-14T10:04:04.000Z",
    "date_insert": "2021-12-14T11:01:03.195Z",
    "date_join": "2021-12-14T10:03:30.000Z",
    "date_start": "2021-12-14T10:03:14.000Z",
    "date_stop": "2021-12-14T10:04:04.000Z",
    "direction": "inbound",
    "disconnect_cause": 16,
    "disconnect_originator": "src",
    "disconnect_reason": "Normal",
    "duration": "50",
    "duration_meeting": "34",
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
    "node": "11.22.33.44",
    "number_dst": "15162065515",
    "number_src": "+17605692222",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "role": "host",
    "user_agent": "CX-IVS-SBC"
}
Attribute Data Type Description
address_dst read only string The fully qualified address of the called party which includes the SIP information with special characters formatted.
address_src read only string The fully qualified address of the calling party which includes the SIP information with special characters formatted.
bridge read only string The name of the bridge which handled the call.
call_sid read only string The secure ID of the call which the system uses to identify it among other calls.
custom_call_type read only string The special field used to identify the origin of the call. Values accepted in this field are:
  • dc for the service DC link initiated and assigned by the bridge.
  • foreign for the third-party VoIP or PSTN clients.
  • private_asd for the native controlling client initiated and assigned by the bridge.
  • private_call for the native clients, i.e. the clients that are using a specific VoIP library.
  • recording for the meeting recording service call initiated and assigned by the bridge.
custom_name read only string The custom name for the calling party set by the software used, web, or IVR with special characters formatted.
date_disconnected read only string The date and time when the call was disconnected from the meeting.
date_insert read only string The date and time when the detail record about the call was inserted into the database.
date_join read only string The date and time when the calling party joined the meeting.
date_start read only string The date and time when the call started.
date_stop read only string The date and time when the call ended.
direction read only string The call direction, either inbound or outbound.
disconnect_cause read only integer The numeric SIP code used to describe the reason to drop the call.
disconnect_originator read only string The initiator of the disconnection. Values accepted in this field are:
  • bridge for the conference bridge to be the disconnection originator (this can happen, when the host leaves the meeting and the meeting is over for all other participants).
  • src for the calling party to be the disconnection originator (i.e., when the participant decides to leave the meeting).
disconnect_reason read only string The detailed descriptive information about the reason to drop the call.
duration read only number The total call duration, specified in seconds.
duration_meeting read only number The duration of the caller’s participation in the meeting, specified in seconds.
endpoint_sid read only string The secure ID of the Conference endpoint associated with the call.
meeting_room_sid read only string The secure ID of the meeting room with which the meeting is associated. This field is available for the secured call flow type, and for the open call flow type when the calling party enters an access code for an existing meeting room.
meeting_sid read only string The secure ID of the meeting in which the calling party participated.
node read only string The IP address of the bridge node.
number_dst read only string The called party phone number.
number_src read only string The calling party phone number.
partner_sid read only string The secure ID of the partner with which the Conference endpoint is associated.
role read only string The role of the calling party in the meeting. Values accepted in this field are:
  • host for the calling party which joined the meeting as the meeting moderator, or host.
  • listener for the calling party which joined the meeting as the user that can only listen to the meeting.
  • participant for the calling party which joined the meeting as the user which can speak, but does not have moderator (host) rights.
user_agent read only string The details about the user agent used by the calling party, if available.

Get Conference Calls

GET /app/conference/calls
Returns Conference endpoint Call object call detail records matching the criteria in the request URL

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

Response 200 response code with a list of App DR Conf CDR objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
            "address_src": "<sip:+17605692222@12.34.56.78",
            "audio_key": null,
            "bridge": "conference-bridge",
            "call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
            "custom_call_type": null,
            "custom_name": null,
            "date_disconnected": "2021-12-14T10:04:04.000Z",
            "date_insert": "2021-12-14T11:01:03.195Z",
            "date_join": "2021-12-14T10:03:30.000Z",
            "date_start": "2021-12-14T10:03:14.000Z",
            "date_stop": "2021-12-14T10:04:04.000Z",
            "direction": "inbound",
            "disconnect_cause": 16,
            "disconnect_originator": "src",
            "disconnect_reason": "Normal",
            "duration": "50",
            "duration_meeting": "34",
            "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
            "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
            "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
            "node": "11.22.33.44",
            "number_dst": "15162065515",
            "number_src": "+17605692222",
            "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
            "role": "host",
            "user_agent": "CX-IVS-SBC"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of call detail records related to the Conference Call objects.

GET /app/conference/calls

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

Required Scopes

To get information about App DR Conf CDR objects, the partner must have one of the following scopes enabled:

To view information about App DR Conf CDR objects for the inherited partner, the partner must additionally have the app.read_descendant scope enabled.

Get Conference Call by SID

GET /app/conference/calls/{call_sid}
Returns a call detail record related to Conference call, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/calls/69057c3e-bb90-4ed3-9c53-000000001142' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 response code with a serialized copy of the App DR Conf CDR object

{
    "address_dst": "\"15162065515\" <sip:15162065515@11.22.33.44>",
    "address_src": "<sip:+17605692222@12.34.56.78",
    "audio_key": null,
    "bridge": "conference-bridge",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000001142",
    "custom_call_type": null,
    "custom_name": null,
    "date_disconnected": "2021-12-14T10:04:04.000Z",
    "date_insert": "2021-12-14T11:01:03.195Z",
    "date_join": "2021-12-14T10:03:30.000Z",
    "date_start": "2021-12-14T10:03:14.000Z",
    "date_stop": "2021-12-14T10:04:04.000Z",
    "direction": "inbound",
    "disconnect_cause": 16,
    "disconnect_originator": "src",
    "disconnect_reason": "Normal",
    "duration": "50",
    "duration_meeting": "34",
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
    "node": "11.22.33.44",
    "number_dst": "15162065515",
    "number_src": "+17605692222",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "role": "host",
    "user_agent": "CX-IVS-SBC"
}

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

GET /app/conference/calls/{call_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about an App DR Conf CDR object, the partner must have one of the following scopes enabled:

To view information about App DR Conf CDR objects for the inherited partner, the partner must additionally have the app.read_descendant scope enabled.

Path Arguments
Parameter Data Type Description
call_sid required string The conference call secure ID.

App DR Conf MDR Object

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

Sample App DR Conf MDR Object object

{
    "attendee_count": 2,
    "audio_attendee_count": 2,
    "control_attendee_count": 0,
    "data_attendee_count": 0,
    "date_insert": "2021-12-14T11:01:20.224Z",
    "date_start": "2021-12-14T10:02:26.000Z",
    "date_stop": "2021-12-14T10:04:04.000Z",
    "duration": "98",
    "duration_audio": "98",
    "duration_control": "0",
    "duration_data": "0",
    "duration_meeting": "98",
    "duration_recording": "0",
    "duration_video": "0",
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "has_recording": false,
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "unique_attendee_count": 2,
    "video_attendee_count": 0
}
Attribute Data Type Description
attendee_count read only integer The total number of the meeting attendees.
audio_attendee_count read only integer The number of the attendees which used audio conferencing during the meeting.
control_attendee_count read only integer The number of the attendees which used conference controls during the meeting.
data_attendee_count read only integer The number of the attendees which sent some data during the meeting.
date_insert read only string The date and time when the detail record about the meeting was inserted into the database.
date_start read only string The date and time when the meeting started.
date_stop read only string The date and time when the meeting ended.
duration read only number The total conference duration, measured in seconds.
duration_audio read only number The duration of the meeting audio conferencing, measured in seconds.
duration_control read only number The duration of the conference control usage during the meeting, measured in seconds.
duration_data read only number The duration of the meeting during which some data was sent or received (e.g., the participants used the screensharing feature), measured in seconds.
duration_meeting read only number The duration of the meeting, measured in seconds.
duration_recording read only number The duration of the meeting during which the recording was made, measured in seconds.
duration_video read only number The duration of the meeting during which the video conferencing was used, measured in seconds.
endpoint_sid read only string The secure ID of the Conference endpoint associated with the meeting.
has_recording read only boolean Whether or not the meeting was recorded.
meeting_room_sid read only string The secure ID of the meeting room associated with the meeting.
meeting_sid read only string The secure ID of the meeting which the system uses to identify it among other meetings.
partner_sid read only string The secure ID of the partner with which the Conference endpoint is associated.
unique_attendee_count read only integer The number of the unique attendees which took part in the meeting.
video_attendee_count read only integer The number of the attendees which used video conferencing during the meeting.

Get Conference Meetings

GET /app/conference/meetings
Returns Conference endpoint Meeting object detail records matching the criteria in the request URL

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

Response 200 response code with a list of App DR Conf MDR objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attendee_count": 2,
            "audio_attendee_count": 2,
            "control_attendee_count": 0,
            "data_attendee_count": 0,
            "date_insert": "2021-12-14T11:01:20.224Z",
            "date_start": "2021-12-14T10:02:26.000Z",
            "date_stop": "2021-12-14T10:04:04.000Z",
            "duration": "98",
            "duration_audio": "98",
            "duration_control": "0",
            "duration_data": "0",
            "duration_meeting": "98",
            "duration_recording": "0",
            "duration_video": "0",
            "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
            "has_recording": false,
            "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
            "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
            "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
            "unique_attendee_count": 2,
            "video_attendee_count": 0
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of detail records related to the Conference Meeting objects.

GET /app/conference/meetings

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

Required Scopes

To get information about App DR Conf MDR objects, the partner must have one of the following scopes enabled:

To view information about App DR Conf MDR objects for the inherited partner, the partner must additionally have the app.read_descendant scope enabled.

Get Conference Meeting by SID

GET /app/conference/meetings/{meeting_sid}
Returns a detail record related to Conference meeting, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/app/conference/meetings/69057c3e-bb90-4ed3-9c53-000000000392' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 response code with a serialized copy of the App DR Conf MDR object

{
    "attendee_count": 2,
    "audio_attendee_count": 2,
    "control_attendee_count": 0,
    "data_attendee_count": 0,
    "date_insert": "2021-12-14T11:01:20.224Z",
    "date_start": "2021-12-14T10:02:26.000Z",
    "date_stop": "2021-12-14T10:04:04.000Z",
    "duration": "98",
    "duration_audio": "98",
    "duration_control": "0",
    "duration_data": "0",
    "duration_meeting": "98",
    "duration_recording": "0",
    "duration_video": "0",
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "has_recording": false,
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000392",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "unique_attendee_count": 2,
    "video_attendee_count": 0
}

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

GET /app/conference/meetings/{meeting_sid}

This request is enabled for Field Filtering.

Required Scopes

To get information about an App DR Conf MDR object, the partner must have one of the following scopes enabled:

To view information about App DR Conf MDR objects for the inherited partner, the partner must additionally have the app.read_descendant scope enabled.

Path Arguments
Parameter Data Type Description
meeting_sid required string The conference meeting secure ID.

App DR Mediator Object

Sample App DR Mediator object

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

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

Attribute Data Type Description
attributes read only object The attributes of a binding or dialout.
date_insert read only string The date and time when the call detail record was processed and added to the database.
date_start read only string The date and time when the call started or SMS was created.
date_stop read only string The date and time when the call stopped or SMS was delivered (with any status).
date_talk read only string The date and time when the call was answered by the destination side.
direction read only string The direction of the call or SMS. Values accepted in this field are:
  • any
  • inbound
  • outbound
  • undirected
dr_sid read only string The detail record secure ID.
dtmf read only string The DTMF signals used during the call in the binding or dialout.
duration read only number The call duration in seconds. The value is calculated as date_stopdate_start.
endpoint_sid read only string The associated endpoint secure ID.
endpoint_type read only string The associated endpoint type. Values accepted in this field are:
  • conference
  • conference_playback
  • flexml
  • mediator
  • peering_receiver
  • peering_sender
  • system_gateway
  • third_party
  • voicemail
event_type read only string The type of the Mediator event. Values accepted in this field are:
  • binding
  • call
  • dialout
  • meeting
number_dst read only string The destination number.
number_redirect read only string The Mediator redirect number.
number_src read only string The source number.
partner_sid read only string The secure ID of the Partner, to whom this detail record belongs.
reference_sid read only string The secure ID of the Mediator binding or dialout.
type read only string The type of call. Values accepted in this field are:
  • conference_call
  • conference_meeting
  • mediator
  • mms
  • sms
  • telecom
version integer The version of the detail record as it comes from the source.

Get Mediator CDRs

GET /app/mediator/calls
Returns Mediator endpoint call detail records matching the criteria in the request URL

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

Response 200 status code with a list of App DR Mediator objects

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

This request returns a list of call detail records related to the Mediator endpoint.

GET /app/mediator/calls

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

Required Scopes

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

To view information about App DR Mediator objects for the inherited partner, the partner must additionally have the app.read_descendant scope enabled.

Batch

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

Task Object

This section describes the elements of the batch task object.

Sample Task object

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

Create Task

/batch/tasks
Creates a batch task

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

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

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

This request creates a batch task.

/batch/tasks
Required Scopes

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

Body Arguments

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

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

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

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

Get Tasks

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

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

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

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

This request returns a list of tasks.

GET /batch/tasks

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

Required Scopes

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

Get Task by SID

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

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

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

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

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

GET /batch/tasks/{task_sid}

This request is enabled for Pagination.

Required Scopes

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

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

Update Task

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

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

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

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

This request updates a task, targeted by secure ID.

PATCH /batch/tasks/{task_sid}
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

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

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

Response 204 status code with an empty body

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

DELETE /batch/tasks/{task_sid}
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, prefix or file.
Batch Review Item Object
Attribute Data Type Description
description read only string The batch review item description.
fields read only object The batch review item fields, which require reviewing.
sid read only string The batch review item secure ID.
version read only integer The batch review item version.

Get Task Review Items by SID

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

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

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

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

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

GET /batch/tasks/{task_sid}/review_items

This request is enabled for Pagination.

Required Scopes

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

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

Download CSV of Task Review Items by SID

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

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

Response 200 status code and a CSV download

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

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

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.

Task Error Detail Object

This section describes the elements of the Batch Task Error Detail object.

Sample Task Error Detail object

{
    "items": [
        {
            "error": {
                "message": "object validation error",
                "errors": [
                    {
                    "field": "phonenumber",
                    "message": "this phonenumber already exists",
                    "reference_sid": "940f3315-9ae7-4a1a-a66c-2df33933e10c"
                    }
                ]
            }
            "key": "{\"phonenumber\":19796101570}",
        }
    ]
}
Attribute Data Type Description
error read only object The error detail error object.
key read only object The error detail key object.

Get Batch Task Error Details

GET /batch/tasks/{task_sid}/errors
Returns error details data for a batch task, targeted by secure ID

curl -X GET \
'https://qa-api.carrierx.com/core/v2/batch/tasks/2ab7081f-db4a-42b3-b7ed-74e1019f30a6/errors?offset=0&limit=1000' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a list of Error Detail objects

{
    "items": [
        {
            "error": {
                "message": "object validation error",
                "errors": [
                    {
                    "field": "phonenumber",
                    "message": "this phonenumber already exists",
                    "reference_sid": "940f3315-9ae7-4a1a-a66c-2df33933e10c"
                    }
                ]
            }
            "key": "{\"phonenumber\":19796101570}",
        }
    ]
}

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

GET /batch/tasks/{task_sid}/errors

This request is enabled for Pagination.

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

Calls

Calls are communications between two or more phone numbers.

Call Detail Record Object

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

Sample Call Detail Record object

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

Get Call Detail Records

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

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

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

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

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

GET /calls/call_drs

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

Required Scopes

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

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

Get Call Detail Record by SID

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

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

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

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

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

GET /calls/call_drs/{dr_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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

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

Rate Object

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

Sample Rate object

{
    "active": "yes",
    "count": 1,
    "effective_date": "2019-08-23T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.005"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": null,
    "partner_sid": "99953792-bd20-4ed0-a523-8c22788f15v6",
    "rates_plan": {
        "name": "retail_voice_in_rates-2019-07-05",
        "rates_plan_sid": "141e0b1f-ac9b-4347-bd44-cfaef65e6f93"
    },
    "total": 9
}
Parameter Data Type Description
active read only string Whether or not that rate is effective, as determined by effective_date.
effective_date read only string The date and time when the rate becomes effective.
items read only array of objects The rate details. Refer to the table below for more information.
partner_sid read only string The secure ID of the partner associated with the rate.
rates_plan read only object The rate plan. Refer to the table below for more information.
Rate Call Object
Parameter Data Type Description
billing_increment read only number The increment in seconds by which billing will occur. Calls are rounded up to the nearest billing_increment.
billing_minimum read only number The minimum length of the call in seconds for billing.
country_code read only string The ISO 3166-1 alpha-3 code of this rate.
country_name read only string The common country name of this rate.
prefix read only string The prefix of this call rate.
price read only number The price of this rate. The price is per billing_minimum.
Rate Plan Object
Parameter Data Type Description
name read only string The name of the rate plan.
rates_plan_sid read only string The rate plan secure ID.

Get Inbound PSTN Rates

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

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

Response 200 status code with a list of Rate objects

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

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

GET /calls/rates/inbound/pstn

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

Download CSV of Inbound PSTN Rates

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

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

Response 200 status code and a CSV download

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

GET /calls/rates/inbound/pstn/csv

This request is enabled for Field Filtering.

Get Inbound VoIP Rates

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

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

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

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

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

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

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

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

Download CSV of Inbound VoIP Rates

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

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

Response 200 status code and a CSV download

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

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

This request is enabled for Field Filtering.

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

Get Outbound PSTN Rates

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

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

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

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

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

GET /calls/rates/outbound/pstn

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

Download CSV of Outbound PSTN Rates

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

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

Response 200 status code and a CSV download

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

GET /calls/rates/outbound/pstn/csv

This request is enabled for Field Filtering.

Get Outbound VoIP Rates

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

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

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

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

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

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

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

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

Download CSV of Outbound VoIP Rates

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

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

Response 200 status code and a CSV download

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

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

This request is enabled for Field Filtering.

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

Countries

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

Country Object

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

Sample Country object

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

Get Countries

GET /countries
Returns a list of countries

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

Response 200 status code with a list of Country objects

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

This request returns a list of countries.

GET /countries

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

Required Scopes

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

Get Country by ISO Code

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

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

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

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

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

GET /countries/{country_code}

This request is enabled for Field Filtering.

Required Scopes

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

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

Get Country by IP Address

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

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

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

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

This request returns the country associated with the IP address.

GET /countries/ip/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
ip_address required string The IPv4 address.

Endpoints

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

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

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

Endpoint Object

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

Sample Endpoint object

{
    "addresses": [],
    "attributes": {},
    "capacity": 0,
    "endpoint_sid": "358d56f9-1482-4b3d-85a9-efd29afc6ff2",
    "name": "my_conf",
    "out_sip_password": null,
    "out_sip_username": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "properties": {
        "account_sid": "6DcA986G-vcBel19O02iIbYUAawVidvB",
        "api_url": "https://api.carrierx.com/conference/v1",
        "container_sid": "null",
        "login": "sample_conference_775",
        "password": "YnAa9s8ixJKi"
    },
    "transformations": [],
    "type": "conference",
    "voip_token": null
}
Attribute Data Type Description
addresses create update array of objects The endpoint addresses. Refer to the table below for more information.
attributes create update object The endpoint attributes. Refer to the table below for more information.
capacity create update integer The maximum number of simultaneous inbound and outbound calls.
endpoint_sid read only string The endpoint secure ID.
name create update string The endpoint name.
out_sip_password create string For calls sent to this endpoint and if proxy authentication is required, this password and out_sip_username will be used if no sip_password is set for the Endpoint Address object.
out_sip_username create string For calls sent to this endpoint and if proxy authentication is required, this username and out_sip_password will be used if no sip_username is set for the Endpoint Address object.
partner read only object The Partner object associated with the endpoint. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid create string The secure ID of the partner associated with the endpoint.
properties create update object The endpoint properties. Refer to the table below for more information.
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 legacy endpoint that allows conference meeting rooms.
  • conference_playback for the hosted endpoint helper for Conference to allow playback of recorded files.
  • conference_v2 for the hosted new endpoint that allows conference meeting rooms.
  • flexml for the hosted endpoint that runs customizable call flows for numbers.
  • mediator for the hosted endpoint that runs two-stage dialing application.
  • peering_receiver for the hosted endpoint that allows inbound connections but has no application attached to it.
  • peering_sender for the hosted endpoint that allows outbound connections but has no application attached to it.
  • system_gateway for the virtual endpoint that represents the CarrierX switch to the customer. This endpoint is created automatically when a new partner is created and is not modifiable.
  • third_party for a standard SIP endpoint that is configured using IP/port pairs.
  • voicemail for the hosted Voicemail endpoint.
voip_token read only string The endpoint authentication token.
Endpoint Address Object
Attribute Data Type Description
direction create update string The direction for the address. Values accepted in this field are: inbound, outbound, and any. The default value for this field is any.
dst_port create update integer If specified, this entry is only valid for calls that reach CarrierX on this port. CarrierX listens on port 5060-5069, and any of these ports may be specified. The default port value is 5060.
ip create update string The IP address or fully qualified domain name (FQDN) associated with the endpoint.
location_sid create update string The location secure ID.
port create update integer The port. The default port value is 5060.
priority create update integer The priority of the address. Lower values have higher priority. The default value is 0.
sip_password create update string For calls sent to this endpoint and if proxy authentication is required, this password and sip_username will be used. This value overrides the out_sip_password value of the Endpoint object.
sip_username create update string For calls sent to this endpoint and if proxy authentication is required, this username and sip_password will be used. This value overrides the out_sip_username value of the Endpoint object.
srtp create update boolean Allows the endpoint to receive and send calls that require the use of secure real-time transport protocol (SRTP). Values accepted in this field are:
  • true for the endpoint to accept and send SIP INVITE requests which require the use of SRTP. You should set the transport attribute to tls for this option to work.
  • false for the endpoint to drop SIP INVITE requests that require the use of SRTP, and to send INVITE using unencrypted RTP.
The default value is false.
subnet_mask create update integer The subnet mask associated with the endpoint. The default value for this field is 32. This value cannot be changed unless the endpoint direction is “outbound”. When set, calls can be accepted from any IP address within the range defined by the IP field and the subnet mask field. For outbound endpoints values within the range between 29 and 32 are allowed. To modify this range, please contact technical support at support@carrierx.com.
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. FlexML, Mediator
api_url create update string The URL of the API. FlexML, Mediator
did_group_id create update string The DID group ID. Conference, FlexML
key create update string The attribute key. Any
subscriber_sid create update string The subscriber secure ID. Conference, FlexML
value create update string The attribute value. Any
Properties Object
Attribute Data Type Description Applicable Endpoints
account_sid read only string The account secure ID. Conference, Conference Playback, FlexML, Mediator, Voicemail
api_url read only string The URL of the API. Conference, Conference Playback, FlexML, Mediator, Voicemail
callback_method create update string The callback method used with the Voicemail endpoint. Values accepted in this field are POST and GET. The default value is POST. Voicemail
callback_url create update string The callback URL used with the Voicemail endpoint. The default value is null. Voicemail
container_sid create update string The secure ID of the container where recordings will be stored. The default value is null. Conference, FlexML, Voicemail
conference_endpoint_sid create update string The secure ID of the Conference endpoint associated with the Conference Playback endpoint. Conference Playback
greeting create update string The name of the file used as a greeting for the Voicemail endpoint. The default value is null. Voicemail
login read only string The login for the endpoint. Conference, Conference Playback, FlexML, Mediator, Voicemail
max_duration create update number The maximum length of the recording in seconds used with the Voicemail endpoint. Voicemail
password read only string The password for the endpoint. Conference, Conference Playback, FlexML, Mediator, Voicemail
subscriber_sid read only string The subscriber secure ID. Conference

Create Endpoint

/endpoints
Creates an endpoint
The following 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'

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

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

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

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

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

This request creates an endpoint.

/endpoints

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

Required Scopes

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

Body Arguments

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

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

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

Get Endpoints

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

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

Response 200 status code with a list of Endpoint objects

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

This request returns a list of endpoints.

GET /endpoints

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

Required Scopes

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

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

Get Endpoint by SID

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

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

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

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

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

GET /endpoints/{endpoint_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
endpoint_sid required string The endpoint secure ID.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the endpoint should be shown. Values accepted in this field are true and false. The default value is false.

Update Endpoint

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

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

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

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

This request updates an endpoint, targeted by secure ID.

PATCH /endpoints/{endpoint_sid}
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

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

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

Response 204 status code with an empty body

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

DELETE /endpoints/{endpoint_sid}

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
        },
        {
            "amount": "0",
            "country_code": "USA"
            "date_billing_period_end": "2023-07-04T23:59:59.000Z",
            "date_billing_period_start": "2023-06-06T00:00:00.000Z",
            "type": "sms_enablement",
            "usage": 1,
        }  
    ],
    "invoice_sid": "4169705e-4284-482f-8e72-e962a8aaad9d",
    "paid": false,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "pay_items": [],
    "status": "open",
    "tax_items": [
        {
            "amount": "0.32",
            "jurisdiction": "federal",
            "type": "fed_universal_service_fund"
        }
    ]
}
Attribute Data Type Description
amount read only number The amount on the invoice. This is not necessarily due at this time.
amount_due read only number The amount due.
amount_tax read only number The tax amount due.
balance_forward read only number The balance that will be used as balance_previous for the next invoice.
balance_previous read only number The previous balance on the invoice.
date_billing_period_end read only string The date and time when the billing period ends.
date_billing_period_start read only string The date and time when the billing period begins.
date_charge_expected read only string The date and time when the invoice will be charged.
date_charged read only string The date and time when the invoice was charged.
date_created read only string The date and time when the invoice was created.
date_issued read only string The date and time when the invoice was issued.
display_id read only string The ID on the rendered invoice.
invoice_items read only array of objects The details about each of the invoice items. Refer to the table below for more information.
invoice_sid read only string The invoice secure ID.
paid read only boolean Shows if the invoice has been paid. Values accepted in this field are: true and false.
partner read only object The Partner object associated with the invoice. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the invoice.
pay_items read only array of objects The payments made while the invoice was open. Refer to the table below for more information.
status read only string The invoice status. Values accepted in this field are:
  • charging for an invoice that is being charged.
  • complete for an invoice that has been charged.
  • created for an invoice that has been created.
  • declined for an invoice that belongs to a partner without a billing method on file, or an invoice with a payment declined.
  • error for a billing module received an error while processing the invoice; invoice may need to be processed manually.
  • open for an open invoice.
  • pending for an invoice that belongs to a partner with a billing method of check on file; this indicates that a check is anticipated.
  • reviewing for an invoice that is awaiting manual approval.
  • uncollectable for an invoice that will not be paid.
tax_items read only array of objects The tax items details. Refer to the table below for more information.
Invoice Item Object
Attribute Data Type Description
amount read only number The invoice item price total.
country_code read only string The ISO 3166-1 alpha-3 code of the service type associated with this invoice item.
date_billing_period_end read only string The date and time when this item billing period ended.
date_billing_period_start read only string The date and time when this item billing period started.
direction read only string The direction of the call or SMS/MMS, either inbound or outbound.
type read only string The type of call, SMS/MMS, transcription, or text-to-speech used. Values accepted in this field are:
  • adjustment
  • bridge
  • did
  • did_lookup_carrier
  • did_lookup_cnam
  • did_lookup_lrn
  • mms
  • sms
  • sms_enablement
  • toll
  • toll_free
  • transcription_average
  • transcription_high
  • transcription_low
  • tts
usage read only integer The number of times the item was used.
Invoice Pay Item Object
Attribute Data Type Description
amount read only number The amount of payment.
billing_method read only object The billing method that was used for the payment.
check_number read only string The check number that was used for the payment.
date_charged read only string The date and time when the payment was made.
pay_item_sid read only string The pay item secure ID.
status read only string The invoice payment status. Values accepted in this field are:
  • complete
  • declined
  • error
type read only string The invoice payment type. Values accepted in this field are:
  • balance_refund
  • charge_back
  • check
  • check_refund
  • credit
  • credit_card
  • credit_card_prepay
  • credit_card_refund
  • wire
  • wire_refund
Invoice Tax Item Object
Attribute Data Type Description
amount read only number The amount of taxes.
jurisdiction read only string The invoice tax jurisdiction. Values accepted in this field are: county, county_local, federal, local, other, state, state_county_local, and unincorporated.
type read only string The invoice tax type. Values accepted in this field are: business_and_occupation_tax, ca_teleconnect_fund, carrier_gross_receipts, district_tax, district_tax_residential, e911_tax, e911_tax_business, e911_tax_pbx_trunk_line, e911_tax_residential, excise_tax, fed_telecommunications_relay_service, fed_universal_service_fund, fed_usf_a_school, federal_excise_tax, franchise_tax, license_tax, license_tax_business, ny_mctd_184a, ny_mctd_186c, optional_telecommunications_infrastructure_maintenance_fee, puc_fee, sales_tax, sales_tax_business, sales_web_hosting, service_tax, special_tax, state_deaf_and_disabled_fund, state_high_cost_fund, state_poison_control_fund, state_universal_service_fund, statutory_gross_receipts, surcharge, telecom_relay_surcharge, telecommunications_assistance_service_fund, telecommunications_infrastructure_fund, telecommunications_infrastructure_maintenance_fee, transit_tax, trs_business, universal_lifeline_telephone_service_charge, universal_service_fund_access_trunk_line, universal_service_fund_business_line, utility_users_tax, and utility_users_tax_business.

Get Invoices

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

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

Response 200 status code with a list of Invoice objects

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

This request returns a list of invoices.

GET /invoices

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

Required Scopes

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

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

Get Invoice by SID

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

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

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

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

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

GET /invoices/{invoice_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
invoice_sid required string The invoice secure ID.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the invoice should be shown. Values accepted in this field are true and false. The default value is false.

Get Invoice HTML Report by SID

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

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

Response 200 status code with the invoice in the HTML format

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

GET /invoices/{invoice_sid}.html
Required Scopes

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

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

Send Invoice HTML Report by SID to Email Addresses

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

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

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

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

/invoices/{invoice_sid}.html/emails
Required Scopes

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

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

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

Get Invoice PDF Report by SID

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

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

Response 200 status code with the invoice in the PDF format

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

GET /invoices/{invoice_sid}.pdf
Required Scopes

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

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

Send Invoice PDF Report by SID to Email Addresses

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

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

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

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

/invoices/{invoice_sid}.pdf/emails
Required Scopes

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

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

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

Lookup

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

Phonenumber Lookup Object

Sample Phonenumber Lookup object

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

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

Attribute Data Type Description
country_code read only string The ISO 3166-1 alpha-3 code of the country.
details read only object The detail object contains cnam, lrn, and carrier data. Refer to the table below for more information.
e164_format read only string The DID in the E.164 format.
in_country_format read only string The DID in a national format.
international_format read only string The DID in an international format.
phonenumber read only string The phone number.
state read only string Geographic area codes of this DID (for the US DIDs only).
Phonenumber Lookup Detail Object
Attribute Data Type Description
carrier read only object The carrier information for the phone number. Refer to the carrier table for more information.
cnam read only object The cnam information for the phone number. Refer to the cnam table for more information.
lrn read only string The location routing number.
Phonenumber Lookup Detail Carrier Object
Attribute Data Type Description
mcc read only integer The mobile country code.
mnc read only integer The mobile network code.
name read only string The carrier name.
type read only string The type of the DID. Values accepted in this field are: landline, mobile, and unknown.
Phonenumber Lookup Detail Cnam Object
Attribute Data Type Description
name read only string The caller name.
type read only string The caller type.

Get Details for Phone Number

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

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

Response 200 status code with the phone number details

{
    "country_code": "USA",
    "details": {
        "carrier": {
            "mcc": "312",
            "mnc": "850",
            "name": "INTELIQUENT",
            "type": "mobile"
        }
        "cnam": null,
        "lrn": null
    }
    "e164_format": "+14353035210",
    "in_country_format": "(435) 303-5210",
    "international_format": "+1 435-303-5210",
    "phonenumber": "14353035210",
    "state": "UT"
}

This request returns data for the specified phone number.

GET /lookup/dids/{phonenumber}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
phonenumber required string The phone number to look up.
Query Arguments
Parameter Data Type Description
carrier boolean Determines if the carrier information should be shown. Values accepted in this field are true and false.
cnam boolean Determines if the CNAM information should be shown. Values accepted in this field are true and false.
cnam_ttl integer Overrides the default CNAM cache TTL.
country_code string The ISO 3166-1 alpha-3 code of the country for this phone number.
guess string Optional recommendation whether this number is domestic or not. Values accepted in this field are:
  • e164 for international numbers.
  • in_country for the domestic numbers.
The default value is e164.
hlr boolean Determines if the carrier will be looked up in the Home Location Registry. Values accepted in this field are true and false. The default value is true.
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.

Using Home Location Registry for Carrier Lookup

The Home Location Registry (HLR) is an external paid database containing data regarding carriers and subscribers. You can set the hlr query argument of your phone number lookup request to true and the system will make an API call to the HLR. The returned results in this case will most likely be more accurate than the results returned without using this flag. Please note that for using this option you will be charged extra.

On the other hand, if the hlr query argument is set to false, the carrier will be determined without the HLR lookup. Only static databases will be used. In this case the mcc and mnc fields will always be returned as null in the reply. If this option is selected, the results returned will be faster and cheaper but less reliable.

IP2Location Object

Sample IP2Location object

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

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

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

Get Details for IP Address

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

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

Response 200 status code with the IP address details

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

This request returns data for the specified IP address.

GET /lookup/lookup/ip_addresses/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

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

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

CIC Lookup Object

Sample CIC Lookup object

{
    "cic": "5102",
    "resporg": "TZN99"
}

This section outlines the CIC (Carrier Identification Code) Lookup object for outbound calls to toll-free phone numbers. 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
cic read only string The Carrier Identification Code used to route and bill calls in the PSTN.
resporg read only string The identifier of a company that owns and manages the toll-free phone number.

Get CIC Details for Toll-free Phone Number

GET /lookup/toll_free/{tollfree_phonenumber}/{calling_number}/{lata}
Returns a CIC and (optionally) a RespOrg ID for a specific toll-free phone number.

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/toll_free/18002446227/12092551162/490?cic=true&resporg=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the CIC and (optionally) RespOrg details.

{
    "cic": "5102",
    "resporg": "TZN99"
}

This request returns CIC data and (optionally) a RespOrg ID for the specified toll-free phone number.

GET /lookup/toll_free/{tollfree_phonenumber}/{calling_number}/{lata}

This request is enabled for Field Filtering.

Required Scopes

To query the CIC information the partner must have the following scope enabled:

To query the RespOrg information (provided as an option in the scope of the CIC Lookup Object) the partner must have the following scope enabled:

Path Arguments
Parameter Data Type Description
tollfree_phonenumber required string The toll-free phone number to look up a CIC for.
calling_number required string The phone number that is placing the call to the toll-free number.
lata required string LATA: Local Access and Transport Area, a geographic code representing the location of the call origination.
Query Arguments
Parameter Data Type Description
cic boolean Determines whether the CIC information should be looked up and shown in the response. Values accepted in this field are true and false. The default value is true. Returns null if set to false.
cic_ttl integer Overrides the default CIC cache TTL (in seconds).
resporg boolean Determines whether the RespOrg information should be looked up and shown in the response. Values accepted in this field are true and false. The default value is false. Returns null if set to false.
resporg_ttl integer Overrides the default RespOrg cache TTL (in seconds).

RespOrg Lookup Object

Sample RespOrg Lookup object

{
    "cic": null,
    "resporg": "TZN99"
}

This section outlines the RespOrg (Responsible Organization) Lookup object for a toll-free phone number. 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
cic read only string Always returns null.
resporg read only string The identifier of a company that owns and manages the toll-free phone number.

Get RespOrg Details for Toll-free Phone Number

GET /lookup/toll_free/{tollfree_phonenumber}
Returns a RespOrg ID for a specific toll-free phone number.

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/toll_free/8002446227?resporg=true' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with the RespOrg details.

{
    "cic": null,
    "resporg": "TZN99"
}

This request returns RespOrg ID data for a specified toll-free phone number.

GET /lookup/toll_free/{tollfree_phonenumber}

This request is enabled for Field Filtering.

Required Scopes

To query the RespOrg information the partner must have the following scope enabled:

Path Arguments
Parameter Data Type Description
tollfree_phonenumber required string The toll-free phone number to look up a RespOrg’s ID for.
Query Arguments
Parameter Data Type Description
resporg boolean Determines if the RespOrg information should be shown in the response. Values accepted in this field are true and false. The default value is true. Returns null if set to false.
resporg_ttl integer Overrides the default RespOrg cache TTL (in seconds).

OAuth

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

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

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

OAuth Token Object

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

Sample OAuth Token object

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

Generate OAuth Bearer Token

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

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

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

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

This request generates a token for the partner upon request.

/oauth/token
Required Scopes

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

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

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

Generate OAuth Bearer Token for Sub-partner

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

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

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

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

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

/oauth/token/{partner_sid}
Required Scopes

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

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

Revoke OAuth Token

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

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

Response 204 status code with an empty body

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

/oauth/revoke
Required Scopes

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

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

Get All Active OAuth Tokens

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

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

Response 200 status code with token data

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

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

GET /oauth/tokens

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

Required Scopes

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

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

Get OAuth Token by SID

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

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

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

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

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

GET /oauth/tokens/{token_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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

Update OAuth Token

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

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

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

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

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

PATCH /oauth/tokens/{token_sid}
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

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

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

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

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

This request returns the currently logged-in partner.

GET /oauth/whoami

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

Partner Login Object

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

Sample Partner Login object

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

Create Partner Login

This request creates an additional login for a partner.

/oauth/logins
Required Scopes

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

Body Arguments

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

Required fields to create a partner login are:

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

Get Partner Logins

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

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

Response 200 status code with a list of Partner Login objects

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

This request returns a list of partner logins.

GET /oauth/logins

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

Required Scopes

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

Get Partner Login by SID

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

GET /oauth/logins/{login_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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

Update Partner Login

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

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

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

Required Scopes

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

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

JSON representation of the fields and values to be updated.

The field that can be modified is password.

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

Delete Partner Login

Response 204 status code with an empty body

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

DELETE /oauth/logins/{login_sid}
Required Scopes

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

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

Partners

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

Partner Object

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

Sample Partner object

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "5",
    "billing_email": null,
    "callbacks": {
        "sms":"https://example.com/sms-callback-url"
    },
    "charge_at": null,
    "city": null,
    "company_name": "ABC",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0", 
    "date_created": "2019-01-22T17:16:30.844Z",
    "display_id": "CX57121051",
    "login": "john",
    "name": "John Smith",
    "owner_email": null,
    "parent_assigned_acls": [],
    "parent_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "partner_sid": "aeda835c-6627-4f4c-ac73-9edcae95640b",
    "payment_type": "postpay",
    "phonenumber": "180045012323",
    "prepay_amount": null,
    "spending_limit": "100",
    "state": "",
    "status": "unverified",
    "tech_email": null,
    "transformations": [],
    "zip": "90804"
}
Attribute Data Type Description
acls create update array of objects The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information.
address1 create update string The partner address.
address2 create update string The partner address second field.
attributes create update object The partner attributes.
available_scopes read only array The abilities that this specific partner has. This field is for internal use only. Refer to this table for the complete list of available scopes.
balance read only number The current balance of the partner.
billing_email create update string The partner email address used for billing purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas.
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).
  • phonenumber_order for getting callbacks with a confirmation of renting a DID from an external provider successfully.
  • phonenumber_messaging_update to get notifications when SMS/MMS messaging is enabled or disabled for a DID.
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.
daily_spending_limit create update integer The maximum amount that the partner is allowed to spend on the account per day.
daily_spent_amount read only integer The amount that the partner has spent on the account during the current day. If this value exceeds the daily_spending_limit, the partner will be suspended until the end of the day.
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 string The login for web and Core API.
name create update string The partner name.
owner_email create update string The partner primary email address.
parent_assigned_acls create update array of objects The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information.
parent_sid create update string The parent partner secure ID.
partner_sid read only string The partner secure ID.
password create update string The partner password for web and Core API. This field is required to create a partner, but is hidden in the serialized copy of the Partner objects received in responses to the requests for the security reasons.
payment_type create string The type of payment. Values accepted in this field are prepay and postpay. Note that the default value is prepay. To change the payment_type, contact technical support at support@carrierx.com.
phonenumber create update string The partner contact phone number.
prepay_amount create update number The charge amount for prepay customers.
spending_limit create number The maximum amount that a partner is allowed to spend on the account.
state create update string The partner state; two-letter abbreviation code.
status read only string The status of the partner. Values accepted in this field are:
  • active for a partner account that is active.
  • canceled for a partner account that was canceled.
  • deleted for a partner account that was removed.
  • suspended* for a partner account that has been suspended due to low balance.
  • soft_suspended* for a partner account that has been partially suspended due to low balance with the following restriction:
    • outbound SMS and dial-outs to the PSTN and to other CarrierX partners are not allowed: the partner is only allowed to receive calls; outbound traffic routing will be limited to its own DIDs and prefixes only,
    • other billable API calls continue to work and accrue charges as usual.
  • unconfirmed for a partner account that has not been confirmed.
  • unverified for a partner account with an email that has not been verified.
* Depending on the partner configuration, one of the two partner suspension types is available: suspended or soft_suspended. To learn about the conditions of activating the soft_suspended option, please contact support@carrierx.com.
tech_email create update string The partner email address used for technical purposes. If this field is empty, the owner_email is used. In this field, you can add multiple email addresses separated by commas.
transformations create update array of objects The list of transformations that a call will undergo. Refer to the transformations section for more information.
zip create update string The partner zip code.

ACL Object

This object is used with acls and parent_assigned_acls.

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

Create Partner

/partners
Creates a partner

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

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

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

This request creates a partner.

/partners

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

Required Scopes

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

Body Arguments

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

Required fields to create a partner are:

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

Get Partners

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

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

Response 200 status code with a list of Partner objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "acls": [],
            "address1": null,
            "address2": null,
            "attributes": {},
            "available_scopes": [
                "accesscontrol.manage",
                "app.manage",
                "calls.manage",
                "countries.manage",
                "endpoints.manage",
                "invoices.manage",
                "lookup.dids.read",
                "oauth.allow_token_scope_update",
                "oauth.manage",
                "oauth.manage_all_tokens",
                "partners.billing_method.manage",
                "partners.read",
                "partners.update",
                "phonenumber.manage",
                "push.manage",
                "rating.manage",
                "shortener.manage",
                "sms.manage",
                "storage.manage",
                "trunk_groups.manage",
                "trunk_groups.trunks.manage",
                "verification.manage"
            ],
            "balance": "4.4",
            "billing_email": "example@example.com",
            "callbacks": {},
            "charge_at": "20",
            "city": null,
            "company_name": "FreeConferenceCall",
            "country_code": "USA",
            "daily_spending_limit": "500",
            "daily_spent_amount": "0",
            "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

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

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

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

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0",
    "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

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

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

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

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "available_scopes": [],
    "balance": "351.52",
    "billing_email": "example@example.com",
    "callbacks": {},
    "charge_at": "20",
    "city": null,
    "company_name": "CarrierX",
    "country_code": "USA",
    "daily_spending_limit": "500",
    "daily_spent_amount": "0",
    "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:

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

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

Delete Partner

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

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

Response 204 status code with an empty body

This request deletes a partner, targeted by secure ID.

DELETE /partners/{partner_sid}

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

Required Scopes

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

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

Billing Method Object

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

Sample Billing Method object

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

Register Billing Method

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

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

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

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

This request registers the billing method for a customer.

/partners/{partner_sid}/billing_method

Required Scopes

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

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

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

Required fields to create a billing method are:

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

Get Billing Method by Partner SID

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

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

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

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

This request returns information registered for the selected partner.

GET /partners/{partner_sid}/billing_method

This request is enabled for Field Filtering.

Required Scopes

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

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

Delete Billing Method

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

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

Response 204 status code with an empty body

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

DELETE /partners/{partner_sid}/billing_method

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

Required Scopes

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

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

Effective Rate Object

Sample Effective Rate object

{
    "assignment": {
        "active": "yes",
        "assignment_sid": "2aa25903-6312-4c4f-9ea6-bbc7a060e142",
        "direction": "inbound",
        "effective_date": "2017-10-03T00:00:00.000Z",
        "endpoint_sid": null,
        "partner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
        "plan_name": "voice_inbound_rates-2017-10-15",
        "plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
        "sub_type": null,
        "type": "pstn"
    },
    "plan": {
        "date_created": "2017-10-19T14:33:07.000Z",
        "name": "voice_inbound_rates-2017-10-15",
        "owner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
        "plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
        "type": "phonenumber"
    }
}

This section outlines the Effective Rate object. An effective rate is the current rate the partner has. An effective rate is a combination of a rate plan and the actual instance of assigning that rate plan to the partner. 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
assignment read only object Information about the rate assignment used to assign this rate plan to the partner. Every time a rate plan is assigned, a rate assignment record is created. Values returned in this field are:
  • active
  • assignment_sid
  • direction
  • effective_date
  • endpoint_sid
  • partner_sid
  • plan_name
  • plan_sid
  • sub_type
  • type
Refer to the table below for more information.
plan read only object Information about the rate plan associated with this rate assignment. Values returned in this field are:
  • date_created
  • name
  • owner_sid
  • plan_sid
  • type
Refer to the table below for more information.

Rate Assignment Object

Attribute Data Type Description
active read only string Whether this rate assignment is currently active or not. Values returned in this field are no and yes. This field depends on the effective_date value and on the parent partner rate assignments. The assignment becomes active at the time specified in the effective_date attribute. The assignment can be inactive in two cases: until the effective_date has occurred and if it is replaced by a succeeding rate assignment of the same type and a new effective_date.
assignment_sid read only string The rate assignment secure ID.
direction read only string The rate plan direction. Values returned in this field are:
  • inbound to apply the plan to received calls and messages.
  • outbound to apply the plan to sent calls and messages.
  • undirected to apply the plan to actions with no direction specified.
effective_date read only string The date and time when the rate plan goes into effect.
endpoint_sid read only string The secure ID of the endpoint for which this rate plan is effective. This field contains a value only if the rate assignment is of the lcr type. Otherwise it will be null.
partner_sid read only string The secure ID of the partner with which this rate assignment is associated.
plan_name read only string The rate plan name.
plan_sid read only string The rate plan secure ID.
sub_type read only string The rate assignment subtype that this rate plan affects.
  • For VoIP, the subtype is defined by the endpoint type (conference, conference_playback, conference_v2, flexml, mediator, peering_receiver, peering_sender, third_party, and voicemail).
  • For SMS/MMS, the subtype is defined by the from (or from_did) type (toll, toll_free, short_code).
type read only string The rate assignment type. Values returned in this field are: did, event, lcr, mms, pstn, sms, sms_mms_passthrough and voip.

Rate Plan Object

Attribute Data Type Description
date_created read only string The date and time when the rate plan was created.
name read only string The rate plan file name.
owner_sid read only string The secure ID of the partner to whom the rate plan belongs.
plan_sid read only string The rate plan secure ID.
type read only string The rate plan type. Values returned in this field are:
  • event for the rate plans that define the billable events (CNAM lookup, use of Amazon Polly TTS voices, etc.)
  • mcc_mnc for the rate plans that set pricing for sending messages.
  • phonenumber for the rate plans that set pricing for voice calls.
  • phonenumber_classification for the rate plans that can be used with the Rate DID Tier objects.
  • sms_mms_passthrough for the rate plans that set carrier pass-through fees at a global level.

Get Effective Rates for Partner

GET /partners/{partner_sid}/effective_rates
Returns all currently Effective Rates for a specific partner

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

Response 200 status code with a list of Effective Rate objects

{
    "assignment": {
        "active": "yes",
        "assignment_sid": "2aa25903-6312-4c4f-9ea6-bbc7a060e142",
        "direction": "inbound",
        "effective_date": "2017-10-03T00:00:00.000Z",
        "endpoint_sid": null,
        "partner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
        "plan_name": "voice_inbound_rates-2017-10-15",
        "plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
        "sub_type": null,
        "type": "pstn"
    },
    "plan": {
        "date_created": "2017-10-19T14:33:07.000Z",
        "name": "voice_inbound_rates-2017-10-15",
        "owner_sid": "b9Ua99icuAdvDvv2kvlNaPzMLDXwuEYJ",
        "plan_sid": "6ab7df5d-7603-4d1b-8f5e-223b7dee0c6d",
        "type": "phonenumber"
    }
}

This request returns all currently Effective Rates for a specific partner.

GET /partners/{partner_sid}/effective_rates

This request is enabled for Field Filtering.

Required Scopes

To get information about the Effective Rates, 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 whose rate plans will be returned.

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, their supported and active capabilities.

Prefixes allow you to route outbound calls based on the starting segment of the dialed phone number. Prefixes are sequences of digits you can set up to route your outbound calls to a desired trunk group on your partner.

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

{
    "active_capabilities": 4,
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 7,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "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",
    "status": "assigned",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}
Attribute Data Type Description
active_capabilities read only integer The phone number enabled (activated) capabilities. Criteria are similar to the capabilities attribute below. Note that this attribute is fully managed by the system and its status depends on whether SMS/MMS is enabled for a DID. To activate the SMS/MMS capabilities of your rented DIDs, you need to enable them. See also SMS/MMS enablement.
attributes create update object The DID attributes.
callback_url create update string The callback URL to receive events for SMS.
campaign_sid create update string The secure ID of the 10DLC campaign associated with the DID.
capabilities read only integer The phone number supported capabilities. Capabilities represent what this DID is potentially capable of: receiving, sending SMS, MMS, voice calls, etc. This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability:
  • 1 for receiving SMS
  • 2 for sending SMS
  • 4 for voice
  • 8 for receiving MMS
  • 16 for sending MMS
To enable receiving SMS and voice, add 1 and 4 together to make 5. The maximum value for this field is 31 (1 + 2 + 4 + 8 + 16) for all capabilities: SMS (receiving and sending), voice, and MMS (receiving and sending). Note, that by default, SMS/MMS messaging capabilities are disabled for all rented DIDs. To enable these capabilities, you need to have them activated. With non-activated capabilities an error will be returned when trying to send an SMS/MMS. See also the active_capabilities attribute above.
classification_sid read only string The phone number classification secure ID, which can be set to one of the DID Classification object secure IDs.
country_code read only string The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
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 assigned to this DID.
name create update string The DID name. The default value is N/A.
partner read only object The Partner object associated with the DID. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the DID.
phonenumber create string The phone number for the DID in the E.164 format.
price read only number The price of the DID.
state read only string The state or province of the DID.
status read only string The current DID status. Values accepted in this field are:
  • aging for DIDs released but not yet available.
  • assigned for DIDs assigned to the partner.
  • available for DIDs available for renting.
  • deleted for DIDs that have been deleted from the system.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
transformations create update array of objects The transformations that are applied to the DID. Refer to the transformations section for more information.
trunk_group_sid create update string The secure ID of the trunk group associated with the DID.

Rent DID

/phonenumber/dids
Assigns a DID to a partner

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

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

{
    "active_capabilities": 4,    
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 31,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "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",
    "status": "assigned",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request assigns a DID to a partner.

/phonenumber/dids

Required Scopes

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

Body Arguments

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

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

If you do not specify a phone number, the system will assign the first available phone number to you.

If you want to rent a specific phone number, you need to pass it as a value for the phonenumber body attribute.

Query Arguments
Parameter Data Type Description
include_external boolean Determines whether the system should look for a phone number from an external provider in case it cannot locate a DID matching your filter criteria among the DIDs owned by CarrierX. Values accepted in this field are true and false. The default value is false.
filter string Restricts the phone number to be rented by some parameters (e.g., capabilities, state, country_code, etc.) and returns the first available phone number matching the filter when you do not specify any body arguments. If include_external=true the country_code parameter is required except for the case when you pass a specific DID as the phonenumber body argument. If include_external=true only the following combinations of filter parameters and operators are available in the result filter:
  • country_code eq, which must be followed by a 3-letters country code, for example country_code eq "SWE".
  • phonenumber like, which must be followed by a substring containing at least 3 digits. For example, [and] phonenumber like "%555%" or you can even give a specific DID in the filter: [and] phonenumber like "46500729289".
  • capabilities, which must be followed by either bit or eq operator. Please note that external DIDs often have limited capabilities. In most cases, only SMS and voice are supported (capabilities bit 1, 2, and 4; and their combinations), so if you are using a capabilities filter with an external DID, you may need to make sure its number does not exceed 7, otherwise you may get very limited results.

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

Response

The status of the DID you have ordered will depend on whether it is an internal DID from CarrierX or an external one.

In case it is an internal DID, it will immediately get the assigned status.

If you have ordered an external DID, its initial status is pending_assignment meaning that an external order for the DID has been created but not completed yet. After a while it changes to assigned. CarrierX will send you a callback on the external order completion, i.e. when a phone number changes its state from pending_assignment to assigned. The callback is identified as phonenumber_order and is configured by the partner on the Partner object. Please be aware that you cannot use your DID until its status changes to assigned.

Get DIDs

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

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

Response 200 status code with a list of DID objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "active_capabilities": 4,
            "attributes": {},
            "callback_url": null,
            "campaign_sid": null,
            "capabilities": 7,
            "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
            "country_code": "USA",
            "did_group_sid": null,
            "did_sid": "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",
            "status": "assigned",
            "string_key_1": null,
            "string_key_2": null,
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/phonenumber/dids?limit=1&offset=1"
    },
    "total": 2
}

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

GET /phonenumber/dids

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

Required Scopes

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

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

Get DID by SID

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

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

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

{
    "active_capabilities": 4,
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 7,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "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",
    "status": "assigned",
    "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

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

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

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

{
    "active_capabilities": 4,
    "attributes": {
        "name": "main line"
    },
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 7,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "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",
    "status": "assigned",
    "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:

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

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

Release DID

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

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

Response 204 status code with an empty body

This request releases a DID, targeted by secure ID, from the partner account. The DID status changes from assigned to ‘aging’.

DELETE /phonenumber/dids/{did_sid}

Required Scopes

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

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

Browse Available DIDs

GET /phonenumber/available_dids
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'

Response 200 status code with a list of available DID objects

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

This request 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:

Filtering by Location

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

Parameter Description Syntax Examples
latlng Use this option to search for the phone numbers located closer to the area described by geographical coordinates specified. phonenumber nearby latlng:<latitude,longitude> filter=phonenumber+nearby+latlng%3A40.801912%2C-73.9681657
npa Use this option to search for the phone numbers located closer to the area associated with the NANP area code specified. phonenumber nearby npa:<npa> filter=phonenumber+nearby+npa%3A516
zip Use this option to search for the phone numbers located closer to the area associated with the ZIP code specified. phonenumber nearby zip:<zip> filter=phonenumber+nearby+zip%3A10025
Query Arguments
Parameter Data Type Description
include_external boolean Determines whether the system should look for a phone number from an external provider in case it cannot locate a DID matching your filter criteria among the DIDs owned by CarrierX. Values accepted in this field are true and false. The default value is false.
If include_external=true, pagination is not supported; the offset must be 0, the limit is set by the user but the number of records in the response depends on the external provider. The system will try to offer a sufficient amount of DIDs satisfying the request criteria from its internal database first, and if this amount is not sufficient, then the system will send a request to the external DIDs provider. Note that the maximum number of external DIDs shown per request is 10. Internally available phone numbers are shown in the request results list first, followed by external numbers.
Important: if include_external=true the request must contain a filter with the country_code parameter.
If include_external=true only the following combinations of filter parameters and operators are allowed in the result filter:
  • country_code eq required, which must be followed by a 3-letters country code, for example country_code eq "SWE".
  • phonenumber like, which must be followed by a substring containing at least 3 digits. For example, [and] phonenumber like "%555%" or you can even give a specific DID in the filter: [and] phonenumber like "46500729289".
  • capabilities, which must be followed by either bit or eq operator. Please note that external DIDs often have limited capabilities. In most cases, only SMS and voice are supported (capabilities bit 1, 2, and 4; and their combinations), so if you are using a capabilities filter with an external DID, you may need to make sure its number does not exceed 7, otherwise you may get very limited results.

Get Available DID by SID

GET /phonenumber/available_dids/{did_sid}
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'

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

{
    "active_capabilities": 4,
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 7,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "07e3dee3-2f0d-4254-b635-21334ccde8b9",
    "in_country_format": "(516) 206-5573",
    "international_format": "+1 516-206-5573",
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": null,
    "phonenumber": "15162065573",
    "price": "0.6",
    "state": "NY",
    "status": "available",
    "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:

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

DID Messaging Enablement Object

This section outlines the DID Messaging Enablement object. These fields and values make up the JSON response that gets returned when a request is successful.

Sample DID Messaging Enablement object

{
    "enabled": true,
    "status": "enabled",
    "type": "a2p"
}
Attribute Data Type Description
enabled create boolean Whether SMS/MMS messaging is enabled or disabled for this DID. If set to true, messaging is enabled. The default value is false.
status read only string Current status of SMS/MMS messaging for this DID. Values that arereturned in this field are:
  • in_progress
  • enabled
  • disabled
  • failed
The default value is disabled.
type create string Sets the phone number enablement type, a2p or p2p. Values accepted in this field are a2p and p2p. If this value is not set, the phone number will use the partner/global default value. By default, partners are only enabled for a2p messaging. Please contact technical support at support@carrierx.com if you need the p2p messaging type to be enabled on your DIDs.

To be able to send SMS/MMS from a rented DID, messaging must be enabled for that DID.

Enable or Disable SMS/MMS Messaging for DID

/phonenumber/dids/{did_sid}/messaging
Enables or disables SMS/MMS for the rented DID

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3125c23-29dd-41b7-5dbc-89edba59230d/messaging' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-binary '{"enabled": true, "type": "a2p"}' \
-H 'Authorization: Bearer 5ebe03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with information about the status of SMS/MMS enablement for the rented DID.

{
    "enabled": true,
    "status": "in_progress",
    "type": "a2p"
}

If no SMS/MMS capabilities are set for this DID, i.e. if this DID has only voice capabilities, the request will return the 404 status code with the no item error message .

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find item by sid",
            "reference_sid": null
        }
    ]
}

This request enables or disables SMS/MMS messaging for a rented DID.

/phonenumber/dids/{did_sid}/messaging

Required Scopes

To enable SMS/MMS messaging for a rented DID, the partner must have the following scopes enabled:

Path Arguments
Parameter Data Type Description
did_sid required string The DID secure ID.
Body Arguments
Parameter Data Type Description
enabled boolean Determines whether SMS/MMS messaging must be enabled or disabled for the phone number. Values accepted in this field are true and false.
Response

A successful response will be the 200 OK code and the DID status will be one of the following:

To be notified when the messaging status changes for a particular DID, you can set up the phonenumber_messaging_update callback.

Get SMS/MMS Messaging Information for DID

GET /phonenumber/dids/{did_sid}/messaging
Returns the status of SMS/MMS messaging for a rented DID, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/f3115c13-29dd-41b7-5dbc-89edbc59230d/messaging' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with information about the status of SMS/MMS enablement for the rented DID.

{
    "enabled": true,
    "status": "enabled"
    "type": "a2p"
}

If no SMS/MMS capabilities are set for this DID, i.e. if this DID has only voice capabilities, the request will return the 404 status code with the no item error message .

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find item by sid",
            "reference_sid": null
        }
    ]
}

This request returns the status of SMS/MMS messaging for a DID, targeted by secure ID.

GET /phonenumber/dids/{did_sid}/messaging

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 DID secure ID.

DID Classification Object

Sample DID Classification object

{
    "aging_policy": 86400,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "name": "Default"
}

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

Attribute Data Type Description
aging_policy read only string The time during which the phone number is considered aging and cannot be rented again.
classification_sid read only string The DID classification secure ID.
name read only string The DID classification name.

Get DID Classifications

GET /phonenumber/classifications
Returns DID classifications matching the criteria in the request URL

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

Response 200 status code with a list of DID Classification objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "aging_policy": 86400,
            "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
            "name": "Default"
        }
    ],
    "limit": null,
    "offset": null,
    "pagination": {},
    "total": 1
}

This request returns a list of DID classifications.

GET /phonenumber/classifications

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

Required Scopes

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

Get DID Classification by SID

GET /phonenumber/classifications/{classification_sid}
Returns a DID classification, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/classifications/17f4d954-d635-4cda-912b-c2a2fa3a6860' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "aging_policy": 86400,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "name": "Default"
}

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

GET /phonenumber/classifications/{classification_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
classification_sid required string The DID classification secure ID.

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.

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 a two-letter abbreviation format.
zip update string The emergency location zip code.

Get DID Emergency

GET /phonenumber/dids/{did_sid}/emergency
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'

Response 200 status 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 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

PATCH /phonenumber/dids/{did_sid}/emergency
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'

Response 200 status 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

DELETE /phonenumber/dids/{did_sid}/emergency
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'

Response 204 status 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

GET /phonenumber/dids/{did_sid}/line_information
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'

Response 200 status 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

PATCH /phonenumber/dids/{did_sid}/line_information
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'

Response 200 status 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

DELETE /phonenumber/dids/{did_sid}/line_information
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'

Response 204 status 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

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}
Attribute Data Type Description
callback_url create update string The callback URL to receive events for SMS.
did_group_sid read only string The DID group secure ID.
name create update string The name of the DID group.
partner read only object The Partner object associated with the DID group. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the DID group.

Create DID Group

/phonenumber/did_groups
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'

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

{
    "callback_url": null,
    "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 one of the following scopes 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

GET /phonenumber/did_groups
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'

Response 200 status code with a list of DID Group objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "callback_url": null,
            "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 one of the following scopes enabled:

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

Get DID Group by SID

GET /phonenumber/did_groups/{did_group_sid}
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'

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

{
    "callback_url": null,
    "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 one of the following scopes enabled:

Path Arguments
Parameter Data Type Description
did_group_sid required string The secure ID of the DID group.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the DID group should be shown. Values accepted in this field are true and false. The default value is false.

Update DID Group

PATCH /phonenumber/did_groups/{did_group_sid}
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'

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

{
    "callback_url": null,
    "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 one of the following scopes 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.

Fields that can be modified are:

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

Delete DID Group

DELETE /phonenumber/did_groups/{did_group_sid}
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'

Response 204 status 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 one of the following scopes 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": "51625",
    "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 assigned to this prefix.
name create update string The prefix name. The default value is N/A.
partner_sid create update string The secure ID of the partner associated with the prefix.
prefix create update string The prefix that will enable the routing logic.
prefix_sid read only string The prefix secure ID.
source_trunk_group_sid create update string The prefix source trunk group secure ID.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
transformations create update array The prefix transformations.
trunk_group_sid create update string The trunk group secure ID.

Create Prefix

/phonenumber/prefixes
Creates a prefix

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

Response 200 status 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": "51625",
    "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 one of the following scopes 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

GET /phonenumber/prefixes
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'

Response 200 status 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": "51625",
            "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 one of the following scopes 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

GET /phonenumber/prefixes/{prefix_sid}
Returns a prefix, targeted by a 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'

Response 200 status 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": "51625",
    "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 a 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 one of the following scopes 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

PATCH /phonenumber/prefixes/{prefix_sid}
Updates the Prefix object, targeted by a 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'

Response 200 status 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": "51625",
    "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 a 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 one of the following scopes 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

DELETE /phonenumber/prefixes/{prefix_sid}
Deletes a prefix, targeted by a 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'

Response 204 status code with an empty body

This request deletes a prefix, targeted by a secure ID.

DELETE /phonenumber/prefixes/{prefix_sid}
Required Scopes

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

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

LRN Prefix Object

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

Sample LRN Prefix object

{
"attributes": {},
"callback_url": null,
"lrn_prefix_sid": "cea69d91-8db6-27b5-a3b2-d6a4d8b62573",
"lrn_sid": null,
"name": "lrn_prefix_name",
"partner_sid": " e00430c3-a7d0-4666-ab5c-f7202448382f ",
"prefix": "1520",
"source_trunk_group_sid": null,
"string_key_1": "",
"string_key_2": "",
"transformations": [],
"trunk_group_sid": null,
}
Attribute Data Type Description
attributes create update object The LRN prefix attributes.
callback_url create update string The callback URL.
lrn_prefix_sid read only string The LRN prefix secure ID.
lrn_sid read only string The secure ID of the Location Routing Number assigned to this LRN prefix.
name create update string The LRN prefix name. The default value is N/A.
partner_sid create update string The secure ID of the partner associated with the LRN prefix.
prefix create update string The LRN prefix that will enable the routing logic.
source_trunk_group_sid create update string The LRN prefix source trunk group secure ID.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
transformations create update array The LRN prefix transformations.
trunk_group_sid create update string The trunk group secure ID.

Create LRN Prefix

/phonenumber/lrn_prefixes
Creates an LRN prefix

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

Response 200 status code with a serialized copy of the LRN Prefix object

{
    "attributes": {},
    "callback_url": null,
    "lrn_prefix_sid": "cea69d91-8db6-27b5-a3b2-d6a4d8b62573",
    "lrn_sid": null,
    "name": "N/A",
    "partner_sid": "cea69d91-8db6-27b5-a3b2-d6a4d8b62573",
    "prefix": "1520",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request creates an LRN Prefix object.

/phonenumber/lrn_prefixes
Required Scopes

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

Body Arguments

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

A required field to create an LRN prefix is prefix.

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

Get LRN Prefixes

GET /phonenumber/lrn_prefixes
Returns LRN prefixes matching the criteria in the request URL

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

Response 200 status code with a list of LRN Prefix objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "lrn_prefix_sid": "cea69d91-8db6-27b5-a3b2-d6a4d8b62573",
            "lrn_sid": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "prefix": "1520",
            "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 LRN Prefix objects.

GET /phonenumber/lrn_prefixes

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

Required Scopes

To get information about LRN Prefix 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 LRN prefix should be shown. Values accepted in this field are true and false. The default value is false.

Get LRN Prefix by SID

GET /phonenumber/lrn_prefixes/{lrn_prefix_sid}
Returns an LRN prefix, targeted by a secure ID

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

Response 200 status code with a serialized copy of the LRN Prefix object

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

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

GET /phonenumber/lrn_prefixes/{lrn_prefix_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
lrn_prefix_sid required string The LRN prefix secure ID.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the LRN prefix should be shown. Values accepted in this field are true and false. The default value is false.

Update LRN Prefix

PATCH /phonenumber/lrn_prefixes/{lrn_prefix_sid}
Updates an LRN Prefix object, targeted by a secure ID, with the values in the request body

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

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

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

This request updates an LRN prefix, targeted by a secure ID.

PATCH /phonenumber/lrn_prefixes/{lrn_prefix_sid}
PUT /phonenumber/lrn_prefixes/{lrn_prefix_sid}

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

Required Scopes

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

Path Arguments
Parameter Data Type Description
lrn_prefix_sid required string The LRN 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 LRN Prefix object.

Delete LRN Prefix

DELETE /phonenumber/lrn_prefixes/{lrn_prefix_sid}
Deletes an LRN prefix, targeted by a secure ID

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

Response 204 status code with an empty body

This request deletes an LRN prefix, targeted by a secure ID.

DELETE /phonenumber/lrn_prefixes/{lrn_prefix_sid}
Required Scopes

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

Path Arguments
Parameter Data Type Description
lrn_prefix_sid required string The LRN prefix secure ID.

Rate DID Tier Object

This section outlines the Rate DID Tier 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 Tier object

{
    "classification_sid": "3306c614-772b-4477-8f29-714676c6d52c",
    "country_code": null,
    "country_name": null,
    "prefix": null,
    "price_0": "0.15",
    "price_1": "0.12",
    "price_2": "0.1",
    "price_3": "0.07",
    "price_4": "0.05",
    "price_5": "0.02",
    "price_6": "0.01",
    "quantity_0": 0,
    "quantity_1": 3,
    "quantity_2":5,
    "quantity_3": 6,
    "quantity_4": 8,
    "quantity_5": 9,
    "quantity_6": 11
}
Attribute Data Type Description
classification_sid read only string The phone number classification secure ID, which can be set to one of the DID Classification object secure IDs.
country_code read only string The ISO 3166-1 alpha-3 code of this rate.
country_name read only string The country name of this rate.
prefix read only string The number prefix for the DID.
price_0…price_6 read only number The price for this rate, which depends on the quantity of the rented DIDs.
quantity_0…quantity_6 read only integer The number of DIDs, which define the rate price.

Get Rates

GET /phonenumber/rates
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'

Response 200 status code with phone number rates

{
    "active": "yes",
    "count": 1,
    "effective_date": "2017-08-03T00:00:00.000Z",
    "has_more": false,
    "items": [
        {
            "classification_sid": "3306c614-772b-4477-8f29-714676c6d52c",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price_0": "0.15",
            "price_1": "0.12",
            "price_2": "0.1",
            "price_3": "0.07",
            "price_4": "0.05",
            "price_5": "0.02",
            "price_6": "0.01",
            "quantity_0": 0,
            "quantity_1": 3,
            "quantity_2":5,
            "quantity_3": 6,
            "quantity_4": 8,
            "quantity_5": 9,
            "quantity_6": 11
        }
    ],
    "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:

Download CSV with Rates

GET /phonenumber/rates/csv
Returns rates in the CSV format

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

Response 200 status code 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 read only string The country of the short code.
did_group_sid update string The DID group secure ID.
locality read only string The region of the short code.
lrn_sid read only string The secure ID of the Location Routing Number assigned to this short code.
name update string The short code name.
partner_sid read only string The secure ID of the partner associated with the short code.
short_code read only string The short code value.
short_code_sid read only string The short code secure ID.
state read only string The state of the short code.
string_key_1 update string A user-defined string key.
string_key_2 update string A user-defined string key.

Get Short Codes

GET /phonenumber/short_codes
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'

Response 200 status 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 one of the following scopes 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

GET /phonenumber/short_codes/{short_code_sid}
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'

Response 200 status 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 one of the following scopes 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

PATCH /phonenumber/short_codes/{short_code_sid}
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'

Response 200 status 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 one of the following scopes 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.

Browse Coverage

GET /phonenumber/coverage
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'

Response 200 status 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 Examples
filter string Values accepted in this field are:
  • capabilities allows selecting only phone numbers with certain capabilities (SMS, MMS, voice). Use this filter with the eq keyword to search for the exact capabilities value or with the bit keyword and the bit number value if you need a specific capability presence.
  • country_code allows filtering phone numbers by the ISO 3166-1 alpha-3 country code.
  • locality allows filtering phone numbers by locality (city, area, etc.)
  • npa allows filtering phone numbers by North American Numbering Plan area code (three digits).
  • npa_nxx allows filtering phone numbers by the first six digits of a NANP telephone number.
  • state allows filtering phone numbers by the two-letter state notation.
filter=capabilities+bit+4/ filter=capabilities+eq+31/ filter=npa+eq+516/ filter=state+eq+NY
group_by required string Which criteria the results should be grouped by. Values accepted in this field are:
  • country allows grouping the results by the state or territory they belong to.
  • locality allows grouping the results by city or area.
  • npa allows grouping the results by NANP area code (three digits).
  • npa_nxx allows grouping the results by the first six digits of a NANP telephone number.
  • state allows grouping the results by state.
Note that only one value is accepted at a time.
group_by=locality
order string Values accepted in this field are count or key. Only one value is accepted at a time. Refer to the table below for more information on these parameters. order=count+asc
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_key_id": null,
    "apns_p8": null,
    "apns_p12": "MIINlwIBAzCCDV4...MYzDtWcmbI2AgEB",
    "apns_p12_expiration": "2021-08-19T16:03:25.000Z",
    "apns_p12_password": "myStrongPassword",
    "apns_team_id": 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_key_id create update string The key identifier of the Apple token-based authentication key.
apns_p8 create update string The authentication token signing key, the content of a .p8 file with line breaks converted to \n.
apns_p12 create update string The Apple Push Notification P12 certificate, encoded to Base64.
apns_p12_expiration read only string The expiration date and time for the Apple Push Notification P12 certificate.
apns_p12_password create update string The passphrase of the Apple Push Notification P12 certificate.
apns_team_id create update string The team identifier of your team in Apple Developer account.
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 read only object The Partner object associated with the application. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the application.

Create Application to Send Push Notifications

/push/applications
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_key_id":"", "apns_p8":"", "apns_p12":"", "apns_p12_password":"", "apns_team_id":""}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "apns_id": null,
    "apns_key_id": null,
    "apns_p8": null,
    "apns_p12": null,
    "apns_p12_expiration": null,
    "apns_p12_password": null,
    "apns_team_id": 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 adds 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

GET /push/applications
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'

Response 200 status code with a list of Application objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "apns_id": null,
            "apns_key_id": null,
            "apns_p8": null,
            "apns_p12": null,
            "apns_p12_expiration": null,
            "apns_p12_password": null,
            "apns_team_id": 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:

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

Get Application by SID

GET /push/applications/{application_sid}
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'

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

{
    "apns_id": null,
    "apns_key_id": null,
    "apns_p8": null,
    "apns_p12": null,
    "apns_p12_expiration": null,
    "apns_p12_password": null,
    "apns_team_id": 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.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the application should be shown. Values accepted in this field are true and false. The default value is false.

Update Application

PATCH /push/applications/{application_sid}
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'

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

{
    "apns_id": null,
    "apns_key_id": null,
    "apns_p8": null,
    "apns_p12": null,
    "apns_p12_expiration": null,
    "apns_p12_password": null,
    "apns_team_id": 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

DELETE /push/applications/{application_sid}
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'

Response 204 status 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 secure ID of the application installed on the device.
application_version create update string The internal version of the application.
device_sid read only string The device secure ID.
environment create update 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 create update string The application version as assigned by the device operating system.
partner read only object The Partner object associated with the device. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only string The secure ID of the partner associated with the device.
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

/push/devices
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"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status 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

GET /push/devices
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'

Response 200 status 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:

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

Get Device by SID

GET /push/devices/{device_sid}
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'

Response 200 status 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.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the device should be shown. Values accepted in this field are true and false. The default value is false.

Update Device

PATCH /push/devices/{device_sid}
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'

Response 200 status 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

DELETE /push/devices/{device_sid}
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'

Response 204 status 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.

Sample Notification object

{
    "android_click_action": null,
    "android_icon": null,
    "android_sound": null,
    "android_tag": null,
    "body": "This is a test push notification for two registered devices.",
    "collapse_key": null,
    "data": {},
    "ios_badge": null,
    "ios_category": null,
    "ios_collapse_id": null,
    "ios_content_available": true,
    "ios_mutable_content": null,
    "ios_push_type": "alert",
    "ios_sound": null,
    "ios_thread_id": null,
    "ios_topic": null,
    "notification_sid": "d4f37407-f5ca-4242-891f-720efeae387b",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "priority": "normal",
    "recipients": [
        "901dd79e-ff4f-4ff3-9b48-c095dfb4fcef",
        "16e64699-3064-463b-8dc7-96783c08a3d9"
    ],
    "title": "Notification for two recipients",
    "ttl": 60,
}
Attribute Data Type Description
android_click_action create string The action that is performed when a user taps the notification on Android devices. You must have an activity with a matching intent filter in your application.
android_icon create string The icon for the application notifications on Android devices.
android_sound create string The sound file included in the application that will play instead of the default device notification sound for Android devices.
android_tag create string Indicates whether each notification message results in a new entry on the notification center on Android devices. If not specified, each request creates a new notification. If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification center.
body create string The notification body text.
collapse_key create string Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed for Android devices.
data create object A custom data object that is passed back to the application.
ios_badge create integer The badge on the client application home icon used with iOS devices. If not specified, the badge is not changed. If set to 0, the badge is removed.
ios_category create string The notification type. It corresponds to the category payload of the aps dictionary.
ios_collapse_id create string Enables apns-collapse-id header key that allows the application to display only the last message of a group of messages with the same collapse key for iOS devices.
ios_content_available create boolean Defines if the support for the background update notification is enabled or not, allowing iOS to wake up the application in the background. It corresponds to the content-available payload of the aps dictionary.
ios_mutable_content create integer Defines if the content of the notification can be modified before the user device displays it. It corresponds to the mutable-content payload of the aps dictionary.
ios_push_type create string The type of the APNs push notification. This field enables the apns-push-type header key required for watchOS 6 and later, recommended for macOS, iOS, tvOS, and iPadOS. Values accepted in this field are: alert, background, complication, fileprovider, mdm, and voip. Refer to Apple documentation for more information on each push type.
ios_sound create string The sound file included in the application that will play instead of the default device notification sound for iOS devices. You must place the custom sound files in your application bundle or in the Library/Sounds folder of your application container directory before you can use them with notifications.
ios_thread_id create string The application-specific unique category identifier, which ensures that these notifications are differentiated from the rest and grouped together.
ios_topic create string The topic for the notification. It corresponds to the apns-topic key and usually looks like this: com.example.MyApp.
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 for the notification, measured in seconds.

Send Notification

/push/notifications
Sends a notification to the devices with secure IDs listed in recipients

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

Response 200 status code with data about the notification

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

This request sends 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 or multimedia messages to them from CarrierX rented DIDs, as well as receiving voice calls or messages from other phone numbers.

You can get the rates to or from the phone numbers specified in the requests which will be used with the rented DIDs and will depend on the call type (voice or message), or endpoint types (available for 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

{
    "direction": "outbound",
    "duration_billing": "60",
    "price": "0.01400",
    "rate": "0.01400"
}
Attribute Data Type Description
direction read only string The direction of the call. Values accepted in this field are:
  • inbound for receiving the calls from the destination phone number.
  • outbound for sending the calls to the destination phone number.
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 PSTN Call Rate

GET /rating/calls/pstn
Returns rates for PSTN voice calls for the phone number specified in the request

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

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

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

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

GET /rating/calls/pstn
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
direction required string The direction of the call. Values accepted in this field are:
  • inbound for receiving the calls from the destination phone number.
  • outbound for sending the calls to the destination phone number.
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.
partner_sid string The secure ID of the partner for which you want to calculate the call price.
to required string The destination phone number.

Get VoIP Call Rate

GET /rating/calls/voip/{sub_type}
Returns rates for VoIP voice calls for the phone number specified in the request

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

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

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

This request returns the voice-over-IP call rates for the destination phone number and the direction specified in the request.

GET /rating/calls/voip/{sub_type}
Required Scopes

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

Path Arguments
Parameter Data Type Description
sub_type required string The endpoint type which will be used to make or accept the voice call. Values accepted in this field are conference, conference_playback, conference_v2, flexml, mediator, peering_receiver, peering_sender, third_party, and voicemail.
Query Arguments
Parameter Data Type Description
direction required string The direction of the call. Values accepted in this field are:
  • inbound for receiving the calls from the destination phone number.
  • outbound for sending the calls to the destination phone number.
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.
partner_sid string The secure ID of the partner for which you want to calculate the call price.
to required string The destination phone number.

Rating MCC/MNC Response Object

This section outlines the Rating MCC/MNC 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 MCC/MNC Response object

{
    "direction": "outbound",
    "price": "0.01000",
    "rate": "0.01000",
    "segments": "1"
}
Attribute Data Type Description
direction read only string The message direction. Values accepted in this field are:
  • inbound for receiving the message from the destination phone number.
  • outbound for sending the message to the destination phone number.
price read only number The price of the message depending on the message segment rate and segments number.
rate read only number The 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. This field value is always set to 1 for multimedia messages (MMS).

Get MMS Rate

GET /rating/mms/{sub_type}
Returns rates for an MMS sent to or received from the phone number specified in the request

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

Response 200 status code with a serialized copy of the Rating MCC/MNC Response object

{
    "direction": "outbound",
    "price": "0.07000",
    "rate": "0.07000",
    "segments": "1"
}

This request returns the MMS rates for the destination phone number and the direction specified in the request.

GET /rating/mms/{sub_type}
Required Scopes

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

Path Arguments
Parameter Data Type Description
sub_type required string The type of the rating used to calculate the price for the MMS. Values accepted in this field are short_code, toll, and toll_free.
Query Arguments
Parameter Data Type Description
direction required string The direction of the MMS. Values accepted in this field are:
  • inbound for receiving the MMS from the destination phone number.
  • outbound for sending the MMS to the destination phone number.
partner_sid string The secure ID of the partner for which you want to calculate the MMS price.
to required string The destination phone number.

Get SMS Rate

GET /rating/sms/{sub_type}
Returns rates for an SMS sent to or received from the phone number specified in the request

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

Response 200 status code with a serialized copy of the Rating MCC/MNC Response object

{
    "direction": "outbound",
    "price": "0.01000",
    "rate": "0.01000",
    "segments": "1"
}

This request returns the SMS rates for the destination phone number and the direction specified in the request.

GET /rating/sms/{sub_type}
Required Scopes

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

Path Arguments
Parameter Data Type Description
sub_type required string The type of the rating used to calculate the price for the SMS. Values accepted in this field are short_code, toll, and toll_free.
Query Arguments
Parameter Data Type Description
direction required string The direction of the SMS. Values accepted in this field are:
  • inbound for receiving the SMS from the destination phone number.
  • outbound for sending the SMS to the destination phone number.
message_segments required integer The number of the SMS segments that will be used to calculate the total message price.
partner_sid string The secure ID of the partner for which you want to calculate the SMS 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 expires. 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 expires.
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. The default value is 6.
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 read only 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 is disabled.
suffix_pattern create update string The regular expressions 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

/shortener/domains
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'

Response 200 status 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_mode 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

GET /shortener/domains
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'

Response 200 status 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

GET /shortener/domains/{domain_sid}
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'

Response 200 status 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

PATCH /shortener/domains/{domain_sid}
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'

Response 200 status 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_mode 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

DELETE /shortener/domains/{domain_sid}
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'

Response 204 status 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 and time when the link was accessed.
date_created read only string The date and time when the link was created.
destination_url create update string The site where the user will be sent.
domain_sid create 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 never expire. The default value is -1.
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 secure ID of the partner associated with the link.
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.

/shortener/links
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'

Response 200 status 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.

GET /shortener/links
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'

Response 200 status 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:

GET /shortener/links/{link_sid}
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'

Response 200 status 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.

PATCH /shortener/links/{link_sid}
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'

Response 200 status 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.

DELETE /shortener/links/{link_sid}
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'

Response 204 status 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_changed": "2022-04-27T09:34:01.637Z",
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "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": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}
Attribute Data Type Description
date_changed read only string The date and time when the message was last changed.
date_created read only string The date and time when the message was created.
date_status_changed read only string The date and time when the message status last changed.
direction read only string The direction of the message. Values accepted in this field are:
  • any for both the received and sent messages.
  • inbound for received messages.
  • outbound for sent messages.
  • undirected for the messages which direction could not be determined.
from create string The phone number that the message will be from, in the E.164 format. Note, that legacy users may still see the old naming instead (from_did).
group_recipients create array The list of phone numbers that an inbound or outbound mms group message is delivered to, in E.164 format. Please note, that group chat messaging is available for mms type of messaging only. If group_recipients are specified, the message type can only be mms. Please also note, that in case of group chat messaging with multiple recipients the sender is charged for each outbound message individually. The maximum number of DIDs you can use in this field for a group chat is 10 (including the sender’s DID).
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:
  • delivered for the outgoing messages that have been successfully delivered to the recipient.
  • failed for the outgoing messages that failed for some reason.
  • internal_error for the outgoing messages that encountered any type of internal system errors while being sent to the recipient.
  • queued for the outgoing messages accepted by the system, but not yet sent.
  • received for the incoming messages that are received by the rented DID.
  • sending_failed for the outgoing messages that passed through either internal_error or sending_timed_out status.
  • sending_timed_out for the outgoing messages that stuck at the queued status for a certain system-set timeout.
  • sent for the outgoing messages that were sent to the recipient.
  • timed_out for the outgoing messages that have been sent, but then stuck at the sent status for a certain system-set timeout.
  • undelivered for the outgoing messages that passed through the sent status, but could not be delivered to the recipient for some reason (e.g., the destination number is unreachable).
to create string The phone number that the message will be delivered to, in the E.164 format. Note, that legacy users may still see the old naming instead (to_did).
type read only string The type of message. Values returned in this field are mms and sms. The default value is sms if both, the media_urls and group_recipients arrays, are empty. The value is mms if any or both of those arrays contain items.
user_data create update string Some additional user-defined data added to the message. The field max length is 2000.

Send Message

/sms/messages
Sends an SMS message

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

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

{
    "date_changed": "2022-04-27T09:29:26.243Z",
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "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": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}

This request sends 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 an SMS message are:

Required fields to send an MMS message are:

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

Get Messages

GET /sms/messages
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'

Response 200 status code with a list of SMS objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_changed": "2022-04-27T09:29:26.243Z",    
            "date_created": "2019-01-18T21:01:13.415Z",
            "date_status_changed": "2019-01-18T10:01:00.000Z",
            "direction": "outbound",
            "from": "15162065575",
            "group_recipients": [],
            "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": "15162065574",
            "type": "sms",
            "user_data": "test_message"
        }
    ],
    "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 received and sent 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 Message by SID

GET /sms/messages/{message_sid}
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'

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

{
    "date_changed": "2022-04-27T09:29:26.243Z",
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": "2019-01-18T10:01:00.000Z",
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "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": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}

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.

Update Message

PATCH /sms/messages/{message_sid}
Updates the SMS object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/sms/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-H 'Content-Type: application/json' \
--data-binary '{"user_data":"updated_test_message"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "date_changed": "2022-04-27T09:29:26.243Z",
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": "2019-01-18T10:01:00.000Z",
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "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": "15162065574",
    "type": "sms",
    "user_data": "updated_test_message"
}

This request updates a message, targeted by secure ID.

PATCH /sms/messages/{message_sid}
PUT /sms/messages/{message_sid}

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

Required Scopes

To update 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.
Body Arguments

JSON representation of the fields and values to be updated.

The field that can be modified is user_data.

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

SMS Detail Record Object

This section outlines the SMS Detail Record 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 Record object

{
    "date_changed": "2022-11-02T12:31:13.843Z",    
    "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": "17207217011",
    "number_dst": "17207217011",
    "number_external": "12078152557",
    "number_group_dst": [
        "17207217011",
        "17207210038",
        "17575000929"
    ],
    "number_src": "12078152557",
    "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
    "price": "0.005",
    "provider": "tsg",
    "rate": "0.005",
    "status": "sent",
    "type": "mms",
    "user_data": "test_message",
    "version": null
}
Attribute Data Type Description
date_changed read only string The date and time when the message was last changed.
date_insert read only string The date and time when the detail record was inserted to the database.
date_sent read only string The date and time when the message was actually sent.
date_start read only string The date and time of the message creation.
date_stop read only string The 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:
  • any for both the received and sent messages.
  • inbound for received messages.
  • outbound for sent messages.
  • undirected for the messages which direction could not be determined.
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 the 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 the E.164 format.
number_external read only string The non-subscriber number in the 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_group_dst read only array Group of destination numbers. In the case of outbound direction these are the called party DIDs, and in the case of inbound direction these are the calling party DIDs.
number_src read only string The source number in the 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.
rate read only number The rate that the system uses to calculate the price of the message.
status read only string The status of the message. Values accepted in this field are:
  • delivered for the outgoing messages that have been successfully delivered to the recipient.
  • failed for the outgoing messages that failed for some reason.
  • internal_error for the outgoing messages that encountered any type of internal system errors while being sent to the recipient.
  • queued for the outgoing messages accepted by the system, but not yet sent.
  • received for the incoming messages that are received by the rented DID.
  • sending_failed for the outgoing messages that passed through either internal_error or sending_timed_out status.
  • sending_timed_out for the outgoing messages that stuck at the queued status for a certain system-set timeout.
  • sent for the outgoing messages that were sent to the recipient.
  • timed_out for the outgoing messages that have been sent, but then stuck at the sent status for a certain system-set timeout.
  • undelivered for the outgoing messages that passed through the sent status, but could not be delivered to the recipient for some reason (e.g., the destination number is unreachable).
type read only string The type of message. Values returned in this field are mms and sms. The default value is sms if both, the media_urls and group_recipients arrays, are empty. The value is mms if any or both of those arrays contain items.
user_data update string Some additional user-defined data added to the message. The field max length is 2000.
version read only integer The version of the detail record as it comes from the resource.

Get Message Detail Records

GET /sms/message_drs
Returns message detail records matching the criteria in the request URL

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

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

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_changed": "2022-11-02T12:31:13.843Z",    
            "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": "17207217011",
            "number_dst": "17207217011",
            "number_external": "12078152557",
            "number_group_dst": [
                "17207217011",
                "17207210038",
                "17575000929"
            ],
            "number_src": "12078152557",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "mms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

This request returns a list of received and sent messages with their detailed information.

GET /sms/message_drs

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

Required Scopes

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

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

Get Message Detail Record by SID

GET /sms/message_drs/{dr_sid}
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'

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

{
    "date_changed": "2022-04-27T09:32:47.763Z",    
    "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": "17207217011",
    "number_dst": "17207217011",
    "number_external": "12078152557",
    "number_group_dst": [
        "17207217011",
        "17207210038",
        "17575000929"
    ],
    "number_src": "12078152557",
    "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
    "price": "0.005",
    "provider": "tsg",
    "rate": "0.005",
    "status": "sent",
    "type": "mms",
    "user_data": "test_message",
    "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 Record object, the partner must have one of the following scopes enabled:

To view information about an SMS Detail Record 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.

Update Message Detail Record

PATCH /sms/message_drs/{dr_sid}
Updates the SMS Detail Record object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/core/v2/sms/message_drs/92cd9154-2f53-4e62-8b4e-8ff6e4849d16' \
-H 'Content-Type: application/json' \
--data-binary '{"user_data":"updated_test_message"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "date_changed": "2022-04-27T13:24:00.993Z",    
    "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": "17207217011",
    "number_dst": "17207217011",
    "number_external": "12078152557",
    "number_group_dst": [
        "17207217011",
        "17207210038",
        "17575000929"
    ],
    "number_src": "12078152557",
    "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
    "price": "0.005",
    "provider": "tsg",
    "rate": "0.005",
    "status": "sent",
    "type": "mms",
    "user_data": "updated_test_message",
    "version": null
}

This request updates a message detail record, targeted by secure ID.

PATCH /sms/message_drs/{dr_sid}
PUT /sms/message_drs/{dr_sid}

An SMS Detail Record object can be updated using either a PATCH or PUT request.

Required Scopes

To update an SMS Detail Record object, the partner must have one of the following scopes enabled:

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

JSON representation of the fields and values to be updated.

The field that can be modified is user_data.

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

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

GET /sms/rates/outbound/{sub_type}
Returns outbound rates for the selected subtype 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'

Response 200 status 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 assignment subtype. Values accepted in this field are:
  • short_code
  • toll
  • toll_free

Download CSV with Outbound Rates

GET /sms/rates/outbound/{sub_type}/csv
Returns outbound rates for the selected subtype for a partner in the CSV format

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

Response 200 status code and a CSV download

This request returns a list of outbound rates for a partner in the 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 the 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 assignment 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",
    "default_file_lifecycle_action": "no_action",
    "default_file_lifecycle_ttl": -1,
    "default_file_publish": "file_sid",
    "default_file_threshold_include": true,
    "default_file_unique": false,
    "durability_class": "unassigned",
    "encrypted": false,
    "external_attributes": {},
    "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,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_action": null,
    "threshold_available_bytes_percent": null,
    "threshold_available_files_percent": null,
    "threshold_bytes": null,
    "threshold_bytes_target": null,
    "threshold_files": null,
    "threshold_files_target": null,
    "threshold_grace_period": 0,
    "threshold_total_bytes": 0,
    "threshold_total_files": 0,
    "total_bytes": 0,
    "total_files": 0,
    "type": "internal",
    "unique": false
}
Attribute Data Type Description
allow_publish create update boolean Whether or not the files in the container can be published. The default value is true.
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.
default_file_lifecycle_action create update string The value for the lifecycle_action attribute of the File object that will be applied by default when uploading files to the container. The default value is no_action.
default_file_lifecycle_ttl create update integer The value for the lifecycle_ttl attribute of the File object that will be applied by default when uploading files to the container. The default value is -1.
default_file_publish create update string The value for the publish attribute of the File object that will be applied by default when uploading files to the container. The default value is file_sid.
default_file_threshold_include create update boolean The value for the threshold_include attribute of the File object that will be applied by default when uploading files to the container. The default value is true.
default_file_unique create update boolean The value for the unique attribute of the File object that will be applied by default when uploading files to the container. The default value is false.
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 an encrypted disk. The default value for this field is false. Note that this value cannot be changed after the Container object has been created.
external_attributes create update object The set of the attributes necessary to access the external container if the type is set to aws, azure, or gcp. Refer to the section below for more information on this attribute.
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. The default value is 1073741824.
quota_files create update integer The maximum number of files that can be stored in the container. The default value is 100.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
string_key_3 create update string A user-defined string key.
string_key_4 create update string A user-defined string key.
threshold_action create update string The action to be performed when the threshold is exceeded (either the number of files or size in bytes). Values accepted in this field are:
  • delete_lru to trigger the storage cleanup job every 2 minutes and delete least recently used files with the threshold_include attribute set to true. The cleanup job runs until the number of files is below threshold_files_target and threshold_bytes_target values. The job also updates the counters for total_bytes/ total_files and available_bytes_percent/ available_files_percent.
  • no_action to trigger no action when the threshold is exceeded.
  • reject to reject the upload of the files which number or size exceeds the threshold set.
The default value is no_action.
threshold_available_bytes_percent read only integer The size of files in bytes which are included into the threshold calculation in relation to the threshold_bytes value.
threshold_available_files_percent read only integer The number of files which are included into the threshold calculation in relation to the threshold_files value.
threshold_bytes create update integer When this size of files in bytes is exceeded, the system will trigger the storage cleanup job if the threshold_action is set to delete_lru. The value must be less or equal to the quota_bytes attribute value.
threshold_bytes_target create update integer The target size of files in bytes which the system must reach after the storage cleanup job runs. The value must be less or equal to threshold_bytes attribute value.
threshold_files create update integer When this number of files is exceeded, the system will trigger the storage cleanup job if the threshold_action is set to delete_lru. The value must be less or equal to the quota_files attribute value.
threshold_files_target create update integer The target number of files which the system must reach after the storage cleanup job runs. The value must be less or equal to threshold_files attribute value.
threshold_grace_period create update integer The time in seconds during which the system allows uploading files when the limit is reached. This attribute is used when the threshold_action is set to reject. The default value is 0.
threshold_total_bytes read only integer The total size of files in bytes which are included into the threshold calculation, i.e., the files with the threshold_include attribute set to true.
threshold_total_files read only integer The total number of files which are included into the threshold calculation, i.e., the files with the threshold_include attribute set to true.
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.
type create string The type of the container, either CarrierX hosted container or one of the supported external storage services. Values accepted in this field are: The default value for this field is internal.
unique create boolean Whether or not the container key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4) 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.

Supported External Storage

CarrierX allows you to use not only the standard containers hosted with CarrierX, but also several types of external storage. For this, set the container type to either aws, or azure, or gcp.

The following external storage services are supported for containers:

You will need to provide the credentials and specify the storage location for each of the external storage used. You can use only one external storage at a time for a single container. Refer to the tables below to learn what parameters you need to specify for each storage type.

Amazon Simple Storage Service

The following request creates an external container with the data stored in Amazon Simple Storage Service:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"aws","external_attributes":{"aws_access_key":"_AWS_ACCESS_KEY_","aws_bucket_name":"_AWS_BUCKET_NAME_","aws_secret_key":"_AWS_SECRET_ACCESS_KEY_"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Attribute Data Type Description
aws_access_key required string The access key used to access AWS S3.
aws_bucket_name required string The bucket name where the container is stored.
aws_secret_key required string The secret key used to access AWS S3.
Google Cloud Platform

1. The following request creates an external container with the data stored in Google Cloud Platform:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"gcp","external_attributes":{"gcp_bucket_name":"_GCP_BUCKET_NAME_","gcp_project":"_GCP_PROJECT_","gcp_access_token":"_GCP_ACCESS_TOKEN_"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

2. This request also creates an external container with the data stored in Google Cloud Platform but uses a different attributes set:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"gcp","external_attributes":{"gcp_bucket_name":"_GCP_BUCKET_NAME_","gcp_project":"_GCP_PROJECT_","gcp_refresh_token":"_GCP_REFRESH_TOKEN_","gcp_client_id":"_GCP_CLIENT_ID_","gcp_client_secret":"_GCP_CLIENT_SECRET_"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Attribute Data Type Description
gcp_access_token string The access token used to access Google Cloud Platform. This attribure is only required if you do not specify gcp_refresh_token, gcp_client_id, and gcp_client_secret.
gcp_bucket_name required string The bucket name where the container is stored.
gcp_client_id string The client ID used to access Google Cloud Platform. This attribute is only required if you do not specify gcp_access_token.
gcp_client_secret string The client secret used to access Google Cloud Platform. This attribute is only required if you do not specify gcp_access_token.
gcp_project required string The project that will be used to store the recording.
gcp_refresh_token string The refresh token used to access Google Cloud Platform. This attribute is only required if you do not specify gcp_access_token.

Microsoft Azure Blob Storage

1. The following request creates an external container with the data stored in Microsoft Azure Blob storage:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"azure","external_attributes":{"azure_account_name":"_AZURE_ACCOUNT_NAME_","azure_container_name":"_AZURE_CONTAINER_NAME_","azure_account_key":"_AZURE_ACCOUNT_KEY_"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

2. This request also creates an external container with the data stored in Microsoft Azure Blob storage but uses a different attributes set:

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{"type":"azure","external_attributes":{"azure_account_name":"_AZURE_ACCOUNT_NAME_","azure_container_name":"_AZURE_CONTAINER_NAME_","azure_sas_token":"_AZURE_SAS_TOKEN_"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'
Attribute Data Type Description
azure_account_key string The account key used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify azure_sas_token.
azure_account_name required string The account name used to access Microsoft Azure Blob storage.
azure_container_name required string The container name where the container is stored.
azure_sas_token string The SAS token used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify azure_account_key.

Create Container

/storage/containers
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'

Response 200 status 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",
    "default_file_lifecycle_action": "no_action",
    "default_file_lifecycle_ttl": -1,
    "default_file_publish": "file_sid",
    "default_file_threshold_include": true,
    "default_file_unique": false,
    "durability_class": "unassigned",
    "encrypted": false,
    "external_attributes": {},
    "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,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_action": null,
    "threshold_available_bytes_percent": null,
    "threshold_available_files_percent": null,
    "threshold_bytes": null,
    "threshold_bytes_target": null,
    "threshold_files": null,
    "threshold_files_target": null,
    "threshold_grace_period": 0,
    "threshold_total_bytes": 0,
    "threshold_total_files": 0,
    "total_bytes": 0,
    "total_files": 0,
    "type": "internal",
    "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.

Responses

If the request is successful, a 200 response code will be returned with a serialized copy of the Container object.

Otherwise, if an error occurs, the system will return one of the HTTP errors used with CarrierX system.

Container Object Specific Errors

Sample container with the same set of keys already exists error

{
    "message":"object validation error",
    "errors":[
        {
            "field":"unique",
            "message":"container with the same set of keys already exists",
            "reference_sid":"a291fe99-43d6-446f-a63e-91f93030dc7e"
        }
    ]
}

If you try to create a container with the unique attribute set to true and the container key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4), which has already been used with some other container, a 422 (object validation error) error will be returned. It has the following structure:

Response Field Data Type Description
field string The field that caused the error.
message string The detailed error description.
reference_sid string The secure ID of the container, which has the same set of unique keys.

The returned error field value will be set to unique, and the message value will be set to container with the same set of keys already exists, indicating that you try to overwrite an existing unique container with the same container key set.

To avoid this error, you can:

Get Containers

GET /storage/containers
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'

Response 200 status 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",
            "default_file_lifecycle_action": "no_action",
            "default_file_lifecycle_ttl": -1,
            "default_file_publish": "file_sid",
            "default_file_threshold_include": true,
            "default_file_unique": false,
            "durability_class": "unassigned",
            "encrypted": false,
            "external_attributes": {},
            "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,
            "string_key_3": null,
            "string_key_4": null,
            "threshold_action": null,
            "threshold_available_bytes_percent": null,
            "threshold_available_files_percent": null,
            "threshold_bytes": null,
            "threshold_bytes_target": null,
            "threshold_files": null,
            "threshold_files_target": null,
            "threshold_grace_period": 0,
            "threshold_total_bytes": 0,
            "threshold_total_files": 0,
            "total_bytes": 0,
            "total_files": 0,
            "type": "internal",
            "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

GET /storage/containers/{container_sid}
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'

Response 200 status 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",
    "default_file_lifecycle_action": "no_action",
    "default_file_lifecycle_ttl": -1,
    "default_file_publish": "file_sid",
    "default_file_threshold_include": true,
    "default_file_unique": false,
    "durability_class": "unassigned",
    "encrypted": false,
    "external_attributes": {},
    "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,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_action": null,
    "threshold_available_bytes_percent": null,
    "threshold_available_files_percent": null,
    "threshold_bytes": null,
    "threshold_bytes_target": null,
    "threshold_files": null,
    "threshold_files_target": null,
    "threshold_grace_period": 0,
    "threshold_total_bytes": 0,
    "threshold_total_files": 0,
    "total_bytes": 0,
    "total_files": 0,
    "type": "internal",
    "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

PATCH /storage/containers/{container_sid}
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'

Response 200 status 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",
    "default_file_lifecycle_action": "no_action",
    "default_file_lifecycle_ttl": -1,
    "default_file_publish": "file_sid",
    "default_file_threshold_include": true,
    "default_file_unique": false,
    "durability_class": "unassigned",
    "encrypted": false,
    "external_attributes": {},
    "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,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_action": null,
    "threshold_available_bytes_percent": null,
    "threshold_available_files_percent": null,
    "threshold_bytes": null,
    "threshold_bytes_target": null,
    "threshold_files": null,
    "threshold_files_target": null,
    "threshold_grace_period": 0,
    "threshold_total_bytes": 0,
    "threshold_total_files": 0,
    "total_bytes": 0,
    "total_files": 0,
    "type": "internal",
    "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:

  • allow_publish
  • allowed_classifications
  • blocked_classifications
  • default_file_lifecycle_action
  • default_file_lifecycle_ttl
  • default_file_publish
  • default_file_threshold_include
  • default_file_unique
  • external_attributes
  • integer_key_1
  • integer_key_2
  • name
  • parent_container_sid
  • partner_sid
  • publish_domain
  • quota_bytes
  • quota_files
  • string_key_1
  • string_key_2
  • string_key_3
  • string_key_4
  • threshold_action
  • threshold_bytes
  • threshold_bytes_target
  • threshold_files
  • threshold_files_target
  • threshold_grace_period

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

Delete Container

DELETE /storage/containers/{container_sid}
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'

Response 204 status 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_last_accessed": "2021-07-28T09:02:11.208Z",
    "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": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "my_audio.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_include": true,
    "type": "file",
    "unique": false
}
Attribute Data Type Description
container_sid create update string The secure ID of the container which this file belongs to.
content_classification read only string The content classification for the uploaded files. Values accepted in this field are:
  • archive
  • document
  • executable
  • media
  • unknown
The classifications are used for the allowed_classifications and blocked_classifications values of the Container object.
content_duration read only number The duration of the file. This field cannot be modified.
content_format read only string The format of the uploaded file. This field cannot be modified.
content_transcoding_progress read only integer The progress of the content transcoding. This field cannot be modified.
date_last_accessed read only string The date and time when the file was last accessed using the Download Data by File SID method. The date is updated at most once a minute.
date_modified read only string The date and time when the last update of the file took place.
desired_bitrate create integer The desired bit rate for MP3 audio files when no transcoding is required. Values accepted in this field are: 8, 16, 24, 32, 40, 48, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320.
desired_format create update string The desired format for audio and video files. The default value is null, meaning that the file will not be transcoded to any other format. Refer to the table below for all file types supported.
file_access_name create update string The path to the file within the container. This field defaults to the file secure ID with extension, where possible.
file_bytes read only integer The file size, specified in bytes.
file_sid read only string The file secure ID.
integer_key_1 create update integer A user-defined integer key.
integer_key_2 create update integer A user-defined integer key.
lifecycle_action create update string The action to be triggered after lifecycle_ttl has elapsed. Values accepted in this field are:
  • delete to delete the file when its lifecycle TTL comes to an end.
  • no_action to do nothing with the file after its lifecycle TTL elapses.
The default value is no_action and can be set using the default_file_lifecycle_action attribute of the Container object.
lifecycle_ttl create update integer How long in seconds before the lifecycle_action will be triggered. The default value is -1 (or indefinite) and can be set using the default_file_lifecycle_ttl attribute of the Container object.
mime_type create update string The content type of the file.
name create update string The file name.
parent_file_sid create update string The parent file secure ID. Setting a parent_file_sid forms a folder-like structure. Files can have a parent_file_sid and this will organize them in groups. If this field is set, and the parent_file_sid no longer exists, files associated with this folder-like structure will be deleted.
partner_sid read only string The secure ID of the partner the file belongs to.
publish create update string Whether to publicly serve a file, and how to store it. Values accepted in this field are:
  • file_access_name to serve the URL in the following manner: /c/{container_sid}/{file_access_name}
  • file_sid to serve the URL in the following manner: /f/{file_sid}
  • no to not serve the URL via public HTTP.
The default value is file_sid and can be set using the default_file_publish attribute of the Container object.
publish_uri read only string The web accessible URI where the file can be retrieved. This value is only applicable if publish is set to either file_access_name or file_sid.
string_key_1 create update string A user-defined string key.
string_key_2 create update string A user-defined string key.
string_key_3 create update string A user-defined string key.
string_key_4 create update string A user-defined string key.
threshold_include create update boolean Whether the file is taken into account when calculating the threshold_total_bytes, threshold_total_files, threshold_available_files_percent, and threshold_available_bytes_percent attributes of the Container object, and participates in the storage cleanup jobs. The default value is true and can be set using the default_file_threshold_include attribute of the Container object.
type read only string The type of the file. Values accepted in this field are:
  • file is the default value.
  • audio verifies the file type, adds appropriate fields, and allows the ability to transcode to another audio format.
  • video verifies the file type, and acts similarly to the audio type.
  • conference is less commonly used.
The default value is file.
unique create boolean Whether or not the file key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4) must be unique. If you create a file with the unique attribute set to true, other unique files (that also have unique set to true) with the same file key set will not be created. Please set this field when the File object is initially created to avoid errors. The default value for this field is false and can be set using the default_file_unique attribute of the Container object.
desired_format

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

Transcode from Codec will be marked yes if files can be transcoded from this file format.

Transcode to Codec will be marked yes if files can be transcoded to this file format.

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

Upload File

/storage/files
Uploads a file to a container using multipart/form-data content type

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

Uploads a file to a container using application/octet-stream content type

curl -X POST \
'https://api.carrierx.com/core/v2/storage/files?container_sid=cb05c1f4-2398-432c-8314-cc306156281c&name=my_audio.mp3' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@my_audio.mp3' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 201 status code with a serialized copy of the File object

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_last_accessed": "2021-07-28T09:02:11.208Z",
    "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": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "my_audio.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_include": true,
    "type": "file",
    "unique": false
}

This request uploads a file to the specified container.

/storage/files

Required Scopes

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

Query Arguments
Parameter Data Type Description
conflict_action string Action in the case you try to upload a file with the unique field set to true, and a file with the same attributes already exists and conflicts with the one being uploaded. Values accepted in this field are:
  • error to throw an error and abort the file upload.
  • overwrite to overwrite the old file with the new one.
  • overwrite_empty to overwrite the old file with the new one only in the case the old file has 0 bytes length.
The argument is used for file uploads with both the multipart/form-data and application/octet-stream content types. The default value is error.
container_sid string The secure ID of the container where the file will be uploaded. Required if you upload the file using the application/octet-stream content type, and not used with the multipart/form-data content type.
Form Arguments

Parameter Data Type Description
data required file path The path of the file to be uploaded.
file_object required object The fields and values of the file to be uploaded. You need to specify at least the container_sid attribute of the File object to successfully upload it. Refer to this table to view all fields that appear in the File object.
Body Arguments

Parameter Data Type Description
file required file path The path of the file to be uploaded.
Responses

If the request is successful, a 201 response code will be returned with a serialized copy of the File object.

Otherwise, if an error occurs, the system will return one of the HTTP errors used with CarrierX system.

File Object Specific Errors
Unique Files Errors

Sample overwrite_empty cannot be applied because container has non-empty files error

{
    "message": "object validation error",
    "errors": [
        {
            "field": "conflict_action",
            "message": "overwrite_empty cannot be applied because container has non-empty files",
            "reference_sid": "c1d71642-643d-4f56-89f6-3bef3f5e22e7"
        }
    ]
}

Sample file with the same set of keys already exists error

{
    "message":"object validation error",
    "errors":[
        {
            "field":"unique",
            "message":"file with the same set of keys already exists",
            "reference_sid":"f6070be2-9abd-4726-870c-c86c9aac5c7e"
        }
    ]
}

If you try to upload a file with the unique attribute set to true and the file key set (integer_key_1, integer_key_2, string_key_1, string_key_2, string_key_3, and string_key_4), which has already been used with some other file, a 422 (object validation error) error will be returned. It has the following structure:

Response Field Data Type Description
field string The field that caused the error.
message string The detailed error description.
reference_sid string The secure ID of the file, which has the same set of unique keys.

To avoid this error, you can:

File Classifications Errors

Sample blocked content classification error

{
    "message": "object validation error",
    "errors": [
        {
            "field": null,
            "message": "Content data type \"document\" is restricted",
            "reference_sid": null
        }
    ]
}

If you try and upload a file that has the content_classification value equal to one of the blocked_classifications values of the parent Container object, it will produce the 422 error and the file will not be uploaded. The same result will be if the file classification is not in the list of the Container object allowed_classifications attribute (if the allowed_classifications value is equal to anything but null).

To avoid this error, you can:

Get Files

GET /storage/files
Returns files from a container matching the criteria in the request URL

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

Response 200 status code with a list of File objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
            "content_classification": "unknown",
            "content_duration": null,
            "content_format": "mp3",
            "content_transcoding_progress": null,
            "date_last_accessed": "2021-07-28T09:02:11.208Z",
            "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": "no_action",
            "lifecycle_ttl": -1,
            "mime_type": "audio/mpeg",
            "name": "my_audio.mp3",
            "parent_file_sid": null,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "publish": "file_sid",
            "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
            "string_key_1": null,
            "string_key_2": null,
            "string_key_3": null,
            "string_key_4": null,
            "threshold_include": true,
            "type": "file",
            "unique": false
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of files.

GET /storage/files

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

Required Scopes

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

Get File by SID

GET /storage/files/{file_sid}
Returns a file, targeted by secure ID

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

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

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_last_accessed": "2021-07-28T09:02:11.208Z",
    "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": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "my_audio.mp3",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_include": true,
    "type": "file",
    "unique": false
}

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

GET /storage/files/{file_sid}

This request is enabled for Field Filtering.

Required Scopes

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

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

Download Data by File SID

GET /storage/files/{file_sid}/data
Downloads the data for a file, targeted by secure ID

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

Response 200 status code and a download of the file data

This request downloads the data for a file, targeted by secure ID.

GET /storage/files/{file_sid}/data
Required Scopes

To download the data for a file, the partner must have one of the following scopes enabled:

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

Update File

PATCH /storage/files/{file_sid}
Updates the File object, targeted by secure ID, with the values in the request body

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

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

{
    "container_sid": "cb05c1f4-2398-432c-8314-cc306156281c",
    "content_classification": "unknown",
    "content_duration": null,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_last_accessed": "2021-07-28T09:02:11.208Z",
    "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": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "new_name",
    "parent_file_sid": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "threshold_include": true,
    "type": "file",
    "unique": false
}

This request updates a file, targeted by secure ID.

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

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

Required Scopes

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

Path Arguments
Parameter Data Type Description
file_sid required string The file secure ID.
Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete File

DELETE /storage/files/{file_sid}
Deletes a file, targeted by secure ID

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

Response 204 status code with an empty body

This request deletes a file, targeted by secure ID.

DELETE /storage/files/{file_sid}
Required Scopes

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

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

Trunk Groups

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

Trunk Group Object

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

Sample Trunk Group object

{
    "acls": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_last_resort": "first",
    "hard_failure_threshold": 3,
    "name": "New Trunk Group",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "transformations": [],
    "trunk_group_sid": "503167ea-b8a5-4a5d-97e3-d684884da1d8",
    "trunks": [
        {
            "acls": [],
            "allow_forward": "disabled",
            "allow_transfer": false,
            "asn_mode": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": null,
            "in_capacity": 0,
            "in_identity_format": "passthrough",
            "in_identity_mode": "passthrough",
            "in_rfc_4694_mode": "cut_all",
            "location_sid": null,
            "name": "Trunk1",
            "out_capacity": 0,
            "out_identity_mode": "passthrough",
            "out_rfc_4694_mode": "cut_all",
            "priority": 0,
            "relay_sip_headers": [],
            "transformations": [],
            "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
            "weight": 0
        }
    ]
}
Attribute Data Type Description
acls create update array of objects The Access Control Lists associated with the trunk group. Refer to the table below for more information.
external_handlers create update array of objects The list of the external handlers objects that will accept the requests and return a set of actions to perform. Refer to the table below for more information.
hard_failure_codes create update string The list of SIP codes on the basis of which the system defines the trunk failure, separated by ;. If the number of reoccurence of such codes exceeds the hard_failure_threshold value within the period of time defined in the hard_failure_interval, the system will mark the trunk as “dead” until the end of the hard_failure_cooldown time. The default value is 408;.
hard_failure_cooldown create update integer The cooldown interval the system waits before retrying to establish connection over a dead trunk, measured in seconds. The default value is 120.
hard_failure_interval create update integer The interval during which the system checks the number of cause codes (hard_failure_codes), measured in seconds. The default value is 60.
hard_failure_last_resort create update string This attribute specifies what the system must do in case of a hard failure of all the trunks in a trunk group. Possible values in this field are:
  • if first set, then even if all the trunks in the trunk group are dead, the system will still try to establish connection over the first trunk.
  • if reject502 or reject503 is set, then the corresponding the reject code will be returned in the case if no more trunks are available.
The default value is first.
hard_failure_threshold create update integer The number of times the trunk can report the hard_failure_codes within the hard_failure_interval before it is considered “dead”. The default value is 3.
name create update string The trunk group name. If no value is passed at creation, the value assigned will be N/A.
partner read only object The Partner object associated with the trunk group. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid create update string The secure ID of the partner associated with the trunk group.
routing_data create update object The additional routing data for trunks.
routing_type create update string The routing type for trunks. Values accepted in this field are failover and round_robin.
  • For trunk groups with routing_type set to failover, CarrierX will attempt to call the trunk with the lowest priority value first. If the call fails, attempts will be made to call other trunks one by one in order of priority.
  • For trunk groups with routing_type set to round_robin, the calls are sent to all the trunks, distributed among them according to their weight value.
The default value is failover.
sip_options_locations create update array The list of location_sid values. The system will use these locations to monitor SIP options. If empty, the SIP options are disabled for all locations.
sip_options_threshold create update integer The number of SIP pings which must fail or succeed before the system marks the trunk “dead”/”alive”. The default value is 3.
soft_failure_codes create update string The SIP codes on the basis of which the system defines the trunk failure without marking it “dead”, separated by ;.
transformations create update array of objects The transformations associated with the trunk group. Refer to the transformations section for more information.
trunk_group_sid read only string The trunk group secure ID.
trunks read only array of objects The trunks of the trunk group. Refer to the Trunk object for more information.
ACL Object
Attribute Data Type Description
access_control_rules create update array The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction create update string The direction for the access control list. Values accepted in this field are:
  • any to apply the rules from the list to both sent and received calls and messages.
  • inbound to apply the rules from the list to received calls and messages.
  • outbound to apply the rules from the list to sent calls and messages.
  • undirected to apply the rules from the list to actions with no direction specified.
sms_action_false read only string For the Trunk Group Object this field is always null and read-only because Trunk Groups are used for voice only.
sms_action_true read only string For the Trunk Group Object this field is always null and read-only because Trunk Groups are used for voice only.
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.
Trunk Group Handler Object
Attribute Data Type Description
direction create update string The direction of the call that will be processed by the external handlers. Values accepted in this field are:
  • any for any call direction.
  • inbound for the received calls.
  • outbound for the sent calls.
error_handler create update string The action to be executed when the external handler returns an error or fails to respond within the specified timeout. Values accepted in this field are:
  • ignore will ignore the error and continue to treat the call as if the handler did not exist.
  • reject403 will reject the call with the 403 status code.
  • reject503 will reject the call with the 503 status code.
The default value is ignore.
timeout create update integer The maximum time for the external handler to respond in milliseconds. The default value is 250 (i.e., 250 milliseconds).
url create update string The external handler URL.

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

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

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

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

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

External Handler Response

Sample external_handlers response with a reject action

[
    {
        "action": "reject",
        "operands": ["forbidden", "aniblock"]
    }
]

This hander will return a Call-Info SIP header containing the message from the reject action:

Call-Info: "aniblock"

The external handlers support all the transformation actions available in CarrierX. The syntax also follows that of the transformations and includes the action and operands attributes of the selected transformation. The direction attribute is set in the Trunk Group Handler object.

Create Trunk Group

/trunk_groups
Creates a trunk group

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

Response 200 status code with a serialized copy of the Trunk Group object

{
    "acls": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_last_resort": "first",
    "hard_failure_threshold": 3,
    "name": "New Trunk Group",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "transformations": [],
    "trunk_group_sid": "503167ea-b8a5-4a5d-97e3-d684884da1d8",
    "trunks": [
        {
            "acls": [],
            "allow_forward": "disabled",
            "allow_transfer": false,
            "asn_mode": "disable",
            "call_type": "regular",
            "codec": null,
            "endpoint_sid": null,
            "in_capacity": 0,
            "in_identity_format": "passthrough",
            "in_identity_mode": "passthrough",
            "in_rfc_4694_mode": "cut_all",
            "location_sid": null,
            "name": "Trunk1",
            "out_capacity": 0,
            "out_identity_mode": "passthrough",
            "out_rfc_4694_mode": "cut_all",
            "priority": 0,
            "relay_sip_headers": [],
            "transformations": [],
            "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
            "weight": 0
        }
    ]
}

This request creates a trunk group with or without trunks.

/trunk_groups
Required Scopes

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

To create a trunk group with trunks, the partner must additionally have either the trunk_groups.trunks.manage or trunk_groups.trunks.create scope enabled.

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

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

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

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

Get Trunk Groups

GET /trunk_groups
Returns trunk groups matching the criteria in the request URL

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

Response 200 status code with a list of Trunk Group objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "acls": [],
            "hard_failure_codes": "408;",
            "hard_failure_cooldown": 120,
            "hard_failure_interval": 60,
            "hard_failure_last_resort": "first",
            "hard_failure_threshold": 3,
            "name": "New Trunk Group",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "routing_data": null,
            "routing_type": "failover",
            "sip_options_locations": [],
            "sip_options_threshold": 3,
            "soft_failure_codes": "408;",
            "transformations": [],
            "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
            "trunks": [
                {
                    "acls": [],
                    "allow_forward": "disabled",
                    "allow_transfer": false,
                    "asn_mode": "disable",
                    "call_type": "regular",
                    "codec": null,
                    "endpoint_sid": null,
                    "in_capacity": 0,
                    "in_identity_format": "passthrough",
                    "in_identity_mode": "passthrough",
                    "in_rfc_4694_mode": "cut_all",
                    "location_sid": null,
                    "name": "Trunk1",
                    "out_capacity": 0,
                    "out_identity_mode": "passthrough",
                    "out_rfc_4694_mode": "cut_all",
                    "priority": 0,
                    "relay_sip_headers": [],
                    "transformations": [],
                    "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
                    "weight": 0
                }
            ]
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&limit=1&offset=1"
    },
    "total": 14
}

This request returns a list of trunk groups.

GET /trunk_groups

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

Required Scopes

To get information about Trunk Group 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 trunk group should be shown. Values accepted in this field are true and false. The default value is false.
with_trunks boolean Determines whether or not to return trunk groups that have one or more trunks.

Get Trunk Group by SID

GET /trunk_groups/{trunk_group_sid}
Returns a trunk group, targeted by secure ID

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

Response 200 status code with a serialized copy of the Trunk Group object

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "acls": [],
            "hard_failure_codes": "408;",
            "hard_failure_cooldown": 120,
            "hard_failure_interval": 60,
            "hard_failure_last_resort": "first",
            "hard_failure_threshold": 3,
            "name": "New Trunk Group",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "routing_data": null,
            "routing_type": "failover",
            "sip_options_locations": [],
            "sip_options_threshold": 3,
            "soft_failure_codes": "408;",
            "transformations": [],
            "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
            "trunks": [
                {
                    "acls": [],
                    "allow_forward": "disabled",
                    "allow_transfer": false,
                    "asn_mode": "disable",
                    "call_type": "regular",
                    "codec": null,
                    "endpoint_sid": null,
                    "in_capacity": 0,
                    "in_identity_format": "passthrough",
                    "in_identity_mode": "passthrough",
                    "in_rfc_4694_mode": "cut_all",
                    "location_sid": null,
                    "name": "Trunk1",
                    "out_capacity": 0,
                    "out_identity_mode": "passthrough",
                    "out_rfc_4694_mode": "cut_all",
                    "priority": 0,
                    "relay_sip_headers": [],
                    "transformations": [],
                    "trunk_sid": "fd97153a-e466-4de6-9484-c3d4dde72b85",
                    "weight": 0
                }
            ]
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&limit=1&offset=1"
    },
    "total": 14
}

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

GET /trunk_groups/{trunk_group_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
trunk_group_sid required string The Trunk Group secure ID.
Query Arguments
Parameter Data Type Description
with_related boolean Determines if the partner information related to the trunk group should be shown. Values accepted in this field are true and false. The default value is false.
with_trunks boolean Determines whether or not to return trunk groups that have one or more trunks.

Update Trunk Group

PATCH /trunk_groups/{trunk_group_sid}
Updates the Trunk Group object, targeted by secure ID, with the values in the request body

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

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

{
    "acls": [],
    "hard_failure_codes": "408;",
    "hard_failure_cooldown": 120,
    "hard_failure_interval": 60,
    "hard_failure_last_resort": "first",
    "hard_failure_threshold": 3,
    "name": "TrunkGroup4",
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "routing_data": null,
    "routing_type": "failover",
    "sip_options_locations": [],
    "sip_options_threshold": 3,
    "soft_failure_codes": "408;",
    "transformations": [],
    "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0"
}

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

PATCH /trunk_groups/{trunk_group_sid}
PUT /trunk_groups/{trunk_group_sid}

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

Required Scopes

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

To modify the external_handlers field of a trunk group, the partner must additionally have the trunk_groups.allow_external_handlers_update scope enabled.

Path Arguments
Parameter Data Type Description
trunk_group_sid required string The trunk group secure ID.
Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

  • acls
  • hard_failure_codes
  • hard_failure_cooldown
  • hard_failure_interval
  • hard_failure_last_resort
  • hard_failure_threshold
  • name
  • routing_data
  • routing_type
  • sip_options_locations
  • sip_options_threshold
  • soft_failure_codes
  • transformations

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

Delete Trunk Group

DELETE /trunk_groups/{trunk_group_sid}
Deletes a trunk group, targeted by secure ID

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

Response 204 status code with an empty body

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

DELETE /trunk_groups/{trunk_group_sid}

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

Trunk Object

Trunks hold settings that will determine how the system will communicate with an endpoint. Trunks belong to trunk groups.

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

Sample Trunk object

{
    "acls": []
    "allow_forward": "disabled",
    "allow_transfer": false,
    "asn_mode": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "in_capacity": 0,
    "in_identity_format": "passthrough",
    "in_identity_mode": "passthrough",
    "in_rfc_4694_mode": "cut_all",
    "location_sid": null,
    "name": "trunk01",
    "out_capacity": 0,
    "out_identity_mode": "passthrough",
    "out_rfc_4694_mode": "cut_all",
    "priority": 0,
    "relay_sip_headers": [],
    "transformations": [],
    "trunk_sid": "4c51c85c-5355-4a91-bf1e-f33d731bcfa9",
    "weight": 0
}
Attribute Data Type Description
acls create update array of objects The Access Control Lists associated with the trunk. Refer to the table below for more information.
allow_forward create update string Determines how to handle 302 redirects from legB. Values accepted in this field are:
  • direct to treat as direct_uri if user@host is specified in contact URI, or to treat as reroute if only user is specified.
  • direct_uri to create call leg to the SIP URI specified in the contact header. If only user is specified without host, assume the host is unchanged and send to the same destination IP again. The new URI will be placed in REDIRECT_URI field of CDRs.
  • disabled to reject the call.
  • protected to allow forward only if the destination IP is associated with an endpoint address, which has its direction set to inbound and is related to the partner third_party endpoint.
  • reroute to use only the phone number portion of the contact URI. Look this up and place as if it were an outbound call, applying all CarrierX routing rules. This will create a 2nd CDR.
The default value is disabled.
allow_transfer create update boolean Whether or not to allow transfer.
asn_mode create update string Whether or not to allow PASSCALLERCSRC, PASSCALLEECSRC variables for ASN proxy. Values accepted in this field are:
  • disable to disable this feature.
  • read to allow reading of ASN proxy flags.
  • write to allow writing of ASN proxy flags.
  • read_write to allow both reading and writing of ASN proxy flags.
The default value is disable.
call_type create update string The call type. Values accepted in this field are:
  • redirect_302 for 302 redirect.
  • regular for with media.
  • sip_only for SIP only.
The default value is regular.
codec create update string The supported codec. Values accepted in this field are: alaw, g722, g723, g729, gsm, opus8, opus12, opus16, opus24, opus48, ulaw. The default value is null which means that the trunk will use one of the supported codecs from legA.
endpoint_sid create update string The secure ID of the endpoint associated with this trunk.
in_capacity create update integer The maximum number of simultaneous calls which the trunk can receive. Use the -1 value to disable receiving calls by the trunk. 0 means unlimited and is the default value.
in_identity_format create update string Determines the format, in which the data will be sent to legB in the case the in_identity_mode/ out_identity_mode is set to pass the RPID/PAI headers. This setting is only applicable when there is data to be sent. Values accepted in this field are:
  • pai to send the information in the PAI format.
  • passthrough to send the information in the format determined by legA.
  • rpid to send the information in the RPID format.
The default value is passthrough.
in_identity_mode create update string Controls when and how the information about Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers is accepted when the trunk is receiving calls. Values accepted in this field are:
  • always
  • never
  • passthrough
  • rewrite_from
See the out_identity_mode parameter below for more information on this. The default value is passthrough.
in_rfc_4694_mode read only string Controls whether the number portability parameters for the “tel” URI are accepted for the incoming leg. Values accepted in this field are:
  • accept_all for accepting all the RFC-4694 parameters as they are.
  • cic_only for accepting CIC parameter information only.
  • cut_all for cutting all the RFC-4694 parameters information off the incoming leg.
  • rn_npdi for accepting the information for query to NPDB and routing number only.
The default value is cut_all.
location_sid create update string Secure ID of the location object that identifies the Trunk object as belonging to a specific location.
name create update string The trunk name.
out_capacity create update integer The maximum number of simultaneous calls which the trunk can send. Use the -1 value to disable sending calls by the trunk. 0 means unlimited and is the default value.
out_identity_mode create update string Controls whether Remote Party ID (RPID) and P-Asserted-Identity (PAI) headers are passed when the trunk is sending calls. The behavior depends on the in_identity_mode value and RPID/PAI headers presence, and is described in respect to the accepted values below.
  • passthrough and RPID/PAI headers are present:
    • if in_identity_mode = passthrough or in_identity_mode = never, then ‘From’ remains unchanged, PAI header is set to RPID/PAI, privacy flags are preserved.
    • if in_identity_mode = always, then ‘From’ remains unchanged, PAI header is not sent.
    • if in_identity_mode = rewrite_from, then ‘From’ is set to RPID/PAI, PAI header is not sent.
  • never or RPID/PAI headers are missing:
    • if in_identity_mode = passthrough or in_identity_mode = always or in_identity_mode = rewrite_from, then ‘From’ remains unchanged, PAI header is not sent.
    • if in_identity_mode = never, then ‘From’ remains unchanged, PAI header is set to the ‘From’ value.
The default value is passthrough.
out_rfc_4694_mode read only string Controls whether the number portability parameters for the “tel” URI are passed to the outgoing leg. Values accepted in this field are:
  • accept_all for passing all the RFC-4694 parameters as they are.
  • cic_only for passing CIC parameter information only.
  • cut_all for cutting all the RFC-4694 parameters information off the outgoing leg.
  • rn_npdi for passing the information for query to NPDB and routing number only.
The default value is cut_all.
out_sip_ringing_max_ttl create update integer Time in seconds during which an outbound call will continue ringing trying to reach the other party before the call is dropped off. The default value is 180.
priority create update integer Allows to change the routing order for trunks inside a trunk group with the routing_type set to failover. Lower values have higher priority. The default value is 0.
relay_sip_headers create update array The list of the headers from the incoming leg that must be passed to the outgoing leg. This setting applies when the trunk is receiving calls. Regular expressions can be used instead of complete header names (e.g., the X-.* value will relay all the X-headers).
transformations create update array of objects The transformations to apply to the trunk. Refer to the transformations section for more information.
trunk_sid read only string The trunk secure ID.
weight create update integer Allows to distribute the calls among the trunks inside a trunk group with the routing_type set to round_robin. Trunks with bigger values will receive more calls compared to trunks with smaller values.

ACL Object
Attribute Data Type Description
access_control_rules create update array The list of access control rules secure IDs. Refer to the Access Control Rule object for more information about access control rules.
direction create update string The direction for the access control list. Values accepted in this field are:
  • any to apply the rules from the list to both sent and received calls and messages.
  • inbound to apply the rules from the list to received calls and messages.
  • outbound to apply the rules from the list to sent calls and messages.
  • undirected to apply the rules from the list to actions with no direction specified.
sms_action_false read only string For the Trunk Object this field is always null and read-only because Trunks are used for voice only.
sms_action_true read only string For the Trunk Object this field is always null and read-only because Trunks are used for voice only.
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.
  • skip to treat the trunk as if it does not exist at all and send the call on to the next trunk.
  • 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.
  • skip to treat the trunk as if it does not exist at all and send the call on to the next trunk.
  • reject403 to reject the call with the 403 status code.
  • reject503 to reject the call with the 503 status code.

Create Trunk

/trunk_groups/{trunk_group_sid}/trunks
Creates a trunk

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

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

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

This request adds a new trunk to the selected trunk group.

/trunk_groups/{trunk_group_sid}/trunks
Required Scopes

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

Path Arguments
Parameter Data Type Description
trunk_group_sid required string The trunk group secure ID.
Body Arguments

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

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

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

Get Trunks

GET /trunk_groups/{trunk_group_sid}/trunks
Returns trunks, targeted by trunk group secure ID

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

Response 200 status code with a list of Trunk objects

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

This request returns a list of trunks for the trunk group, targeted by secure ID.

GET /trunk_groups/{trunk_group_sid}/trunks

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

Required Scopes

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

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

Get Trunk by SID

GET /trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}
Returns a trunk, targeted by trunk group and trunk secure IDs

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

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

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

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

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

This request is enabled for Field Filtering.

Required Scopes

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

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

Update Trunk

PATCH /trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}
Updates the Trunk object, targeted by trunk group and trunk secure ID, with the values in the request body

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

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

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

This request updates a trunk, targeted by trunk and trunk group secure ID.

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

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

Required Scopes

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

To modify the allow_forward field of a trunk, the partner must additionally have the trunk_groups.trunks.allow_trunk_allow_forward_update scope enabled.

Path Arguments
Parameter Data Type Description
trunk_group_sid required string The trunk group secure ID.
trunk_sid required string The trunk secure ID.
Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

  • acls
  • allow_forward
  • allow_transfer
  • asn_mode
  • call_type
  • codec
  • endpoint_sid
  • in_capacity
  • in_identity_format
  • in_identity_mode
  • in_rfc_4694_mode
  • location_sid
  • name
  • out_capacity
  • out_identity_mode
  • out_rfc_4694_mode
  • priority
  • relay_sip_headers
  • transformations
  • weight

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

Delete Trunk

DELETE /trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}
Deletes a trunk, targeted by trunk group and trunk secure ID

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

Response 204 status code with an empty body

This request deletes a trunk, targeted by trunk and trunk group secure ID.

DELETE /trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}
Required Scopes

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

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

TTS

Text-to-speech API (TTS) allows CarrierX partners record lifelike voice messages without the need to hire professional voice actors. The partners can use such recordings when they need introductory audio records for the incoming calls (e.g., with the FlexML Play verb, etc.). Partners can select the language and voice for their text-to-speech recordings, set the audio format and bitrate, and send the text to receive the audio file with the recording in response, which they can save into CarrierX storage service containers.

TTS Text Object

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

Sample TTS Text object

{
    "bitrate": "32000",
    "format": "mp3",
    "language": "en-US",
    "text": "This is my text for text-to-speech audio.",
    "voice_sid": "Polly.Kimberly"
}
Attribute Data Type Description
bitrate create string The bitrate used for text-to-speech conversion, specified in bits per second. Values accepted in this field are: 8000, 16000, 24000, 32000, 40000, 48000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, and 320000. Please note that not all the formats support all the bitrate values. Refer to the section below for more information on this. The default value is 16000.
format create string The output audio format used for text-to-speech conversion. Values accepted in this field are: al, flac, g722, mp3, mp4, ogg, ul, and wav. Please note that not all the formats support all the bitrate values. Refer to the section below for more information on this. The default value is mp3.
language create string The language used for text-to-speech conversion. Values accepted in this field are: arb, cmn-CN, cy-GB, da-DK, de-DE, en-AU, en-GB, en-GB-WLS, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, is-IS, it-IT, ja-JP, hi-IN, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, and tr-TR. Not all languages might be supported for the selected voice. Refer to the table below for the complete list of the voices with their languages. The default value is en-US.
text create string The text that will be converted into audio with the text-to-speech feature. The maximum number of character allowed for the text is 3000.
voice_sid create string The secure ID of the voice used for text-to-speech conversion. Values accepted in this field are: man, woman, or any of the Amazon Polly voices listed in the table below. The default value is man.

Known Formats Limitations

When you create a voice message, please bear in mind that some of the formats have certain limitations:

Amazon Polly Voices

CarrierX allows its partners to use Amazon Polly voices for their text-to-speech messages conversion. Amazon Polly is a service that turns text into lifelike speech. Polly’s text-to-speech service uses advanced deep learning technologies to synthesize natural sounding human speech. It contains dozens of lifelike voices across a broad set of languages.

Language Language Code Gender Voice
Arabic arb Female Polly.Zeina
Chinese, Mandarin cmn-CN Female Polly.Zhiyu
Danish da-DK Male Polly.Mads
Danish da-DK Female Polly.Naja
Dutch nl-NL Female Polly.Lotte
Dutch nl-NL Male Polly.Ruben
English–Australian en-AU Female Polly.Nicole
English–Australian en-AU Female Polly.Olivia
English–Australian en-AU Male Polly.Russell
English–British en-GB Female Polly.Amy
English–British en-GB Male Polly.Brian
English–British en-GB Female Polly.Emma
English–Indian en-IN Female Polly.Aditi
English–Indian en-IN Female Polly.Raveena
English–US en-US Female Polly.Ivy
English–US en-US Female Polly.Joanna
English–US en-US Male Polly.Joey
English–US en-US Male Polly.Justin
English–US en-US Female Polly.Kendra
English–US en-US Male Polly.Kevin
English–US en-US Female Polly.Kimberly
English–US en-US Male Polly.Matthew
English–US en-US Female Polly.Salli
English–Welsh en-GB-WLS Male Polly.Geraint
French fr-FR Female Polly.Celine
French fr-FR Female Polly.Lea
French fr-FR Male Polly.Mathieu
French–Canadian fr-CA Female Polly.Chantal
German de-DE Male Polly.Hans
German de-DE Female Polly.Marlene
German de-DE Female Polly.Vicki
Hindi hi-IN Female Polly.Aditi
Icelandic is-IS Female Polly.Dora
Icelandic is-IS Male Polly.Karl
Italian it-IT Female Polly.Bianca
Italian it-IT Female Polly.Carla
Italian it-IT Male Polly.Giorgio
Japanese ja-JP Female Polly.Mizuki
Japanese ja-JP Male Polly.Takumi
Korean ko-KR Female Polly.Seoyeon
Norwegian nb-NO Female Polly.Liv
Polish pl-PL Female Polly.Ewa
Polish pl-PL Male Polly.Jacek
Polish pl-PL Male Polly.Jan
Polish pl-PL Female Polly.Maja
Portuguese–Brazilian pt-BR Female Polly.Camila
Portuguese–Brazilian pt-BR Male Polly.Ricardo
Portuguese–Brazilian pt-BR Female Polly.Vitoria
Portuguese–European pt-PT Male Polly.Cristiano
Portuguese–European pt-PT Female Polly.Ines
Romanian ro-RO Female Polly.Carmen
Russian ru-RU Male Polly.Maxim
Russian ru-RU Female Polly.Tatyana
Spanish–Castilian es-ES Female Polly.Conchita
Spanish–Castilian es-ES Male Polly.Enrique
Spanish–Castilian es-ES Female Polly.Lucia
Spanish–Mexican es-MX Female Polly.Mia
US Spanish es-US Female Polly.Lupe
US Spanish es-US Male Polly.Miguel
US Spanish es-US Female Polly.Penelope
Swedish sv-SE Female Polly.Astrid
Turkish tr-TR Female Polly.Filiz
Welsh cy-GB Female Polly.Gwyneth

Create TTS Text

/tts/texts
Creates a TTS text and saves the returned resulting audio stream into a file

curl -X POST \
'https://api.carrierx.com/core/v2/tts/texts' \
-H 'Content-Type: application/json' \
--data-binary '{"text":"This is my text for text-to-speech."}' \
-o my_audio.mp3 \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code and the created audio file


/tts/texts?response_format=file&response_container_sid={response_container_sid}
Creates a TTS text and saves the returned resulting audio stream as a file into CarrierX storage service container

curl -X POST \
'https://api.carrierx.com/core/v2/tts/texts?response_format=file&response_container_sid=a0323bcc-df67-4ad6-845f-9b11bdf4e778' \
-H 'Content-Type: application/json' \
--data-binary '{"text":"This is my text for text-to-speech."}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "container_sid": "a0323bcc-df67-4ad6-845f-9b11bdf4e778",
    "content_classification": "media",
    "content_duration": 1.83,
    "content_format": "mp3",
    "content_transcoding_progress": null,
    "date_modified": "2021-06-21T13:17:32.517Z",
    "desired_bitrate": null,
    "desired_format": null,
    "file_access_name": "51e4a594e191c8c8e516858709470509c5dafa889bd004acd6157673476cdf11.mp3",
    "file_bytes": 3789,
    "file_sid": "f77251d7-0990-455c-a6ae-d83d61121599",
    "integer_key_1": null,
    "integer_key_2": null,
    "lifecycle_action": "no_action",
    "lifecycle_ttl": -1,
    "mime_type": "audio/mpeg",
    "name": "51e4a594e191c8c8e516858709470509c5dafa889bd004acd6157673476cdf11.mp3",
    "parent_file_sid": null,
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "publish": "file_sid",
    "publish_uri": "http://storage-carrierx.com/f/f77251d7-0990-455c-a6ae-d83d61121599",
    "string_key_1": null,
    "string_key_2": null,
    "string_key_3": null,
    "string_key_4": null,
    "type": "audio",
    "unique": false
}

This request creates an audio recording out of a text message.

/tts/texts
Required Scopes

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

Body Arguments

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

Required fields to create a TTS text are:

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

Query Arguments
Parameter Data Type Description
response_container_sid string The secure ID of the container where the output audio file will be stored. If you set this option, the response_format is also required. If this option is omitted, the file will be returned as an audio stream.
response_format string The format of the output audio file. Values accepted in this field are:
  • audio—use this value to return the resulting audio as an audio stream. You can save it using the means of the programming language of your choice (e.g., -o my_audio.mp3 for the cURL POST request).
  • file—use this value together with the response_container_sid parameter to save the resulting audio file into CarrierX storage service container.
The default value is audio.
Responses

If the request is successful, a 200 response code will be returned together with the created audio file (as a file or as an audio stream, depending on the response_format query attribute value).

Otherwise, if an error occurs, the system will return one of the HTTP errors used with CarrierX system.

TTS Text Object Specific Errors
{
    "message":"object validation error",
    "errors":[
        {
            "field":"language",
            "message":"not supported by voice",
            "reference_sid":null
        }
    ]
}

If you set a bitrate, format, language, or voice_sid not from the list of available values, or select an unsupported language for the chosen voice, the request will return a 422 (object validation error) error. It has the following structure:

Response Field Data Type Description
field string The field that caused the error.
message string The detailed error description.
reference_sid string This field is not used and is always set to null, as no object can be created during the request.

To avoid this error, you can:

TTS Voice Object

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

Sample TTS Voice object

{
    "languages": {
        "en-US": 0
    },
    "voice_sid": "Polly.Joanna"
}
Attribute Data Type Description
languages read only object The languages that the voice supports with the voice priority in scope of the language. Smaller values have higher priority.
voice_sid read only string The voice secure ID. Refer to this table for the complete list of the available voices.

Get TTS Voices

GET /tts/voices
Returns TTS voices matching the criteria in the request URL

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

Response 200 status code with a list of TTS Voice objects

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "languages": {
                "en-US": 0
            },
            "voice_sid": "man"
        },
        {
            "languages": {
                "en-US": 0
            },
            "voice_sid": "woman"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 2
}

This request returns a list of TTS voices.

GET /tts/voices

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

Required Scopes

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

Get TTS Voice by SID

GET /tts/voices/{voice_sid}
Returns a TTS voice, targeted by secure ID

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

Response 200 status code with a serialized copy of the TTS Voice object

{
    "languages": {
        "en-US": 0
    },
    "voice_sid": "Polly.Joanna"
}

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

GET /tts/voices/{voice_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
voice_sid required string The TTS voice secure ID.

Verification

Verification enables the system to send out verification emails and text messages, and verify the email address through a token.

Verification Email Object

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

Sample Verification Email object

{
    "base_url": "https://www.carrierx.com/confirmed",
    "email_template_sid": "3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba",
    "partner_sid": null,
    "status": "sent_email",
    "to_address": "jsmith@carrierx.com"
}
Attribute Data Type Description
base_url create string URL to be added to the email before verification token. If not specified, the default is used.
email_template_sid create string The secure ID of the Email Template object on which this verification email is based.
partner_sid create string The secure ID of the partner associated with the verification email.
status read only string The status of the verification. Values accepted in this field are:
  • created
  • sent_email
  • verified
to_address create string The email address to send the verification email.

Send Verification SMS

/verification/sms
Sends a verification SMS

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

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

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

This request sends an outbound message with a unique code generated by the system.

/verification/sms

A verification SMS message has the same structure as a normal SMS message, but the direction will always be outbound and the message string will include a code generated by the system.

Required Scopes

To send a verification SMS message, the partner must have one of the following scopes enabled:

Query Arguments
Parameter Data Type Description
allow_short_code boolean Allow sending verification message from a short code, if any short code is associated with the DID group. The default value is true.
code_length integer The length of the verification code.
code_type string The type of code to generate. Values accepted in this field are:
  • alphabetical
  • alphabetical_lower
  • alphabetical_upper
  • alphanumeric
  • alphanumeric_lower
  • alphanumeric_upper
  • numeric
did_group_sid string The DID group secure ID.
from required string The phone number of the message originator in the E.164 format. Note, that legacy users may still see the old naming instead (from_did).
message string The message to be shown before the unique code. The default string is “Your verification code is”.
to required string The phone number of the recipient in the E.164 format. Note, that legacy users may still see the old naming instead (to_did).

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

Send Verification Email

/verification/email
Sends a verification email

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

Response 200 status code with a serialized copy of the Verification Email object

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

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

/verification/email
Required Scopes

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

Body Arguments

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

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

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

Verify Email by Token

GET /verification/email/tokens/{token}
Verifies the partner verification email through the verification token

curl -X GET \
'https://api.carrierx.com/core/v2/verification/email/tokens/c0438d84-2bde-4342-861b-0815eb72c012' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response 200 status code with a serialized copy of the Verification Email object

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

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

GET /verification/email/tokens/{token}
Required Scopes

To verify email by token, the partner must have one of the following scopes enabled:

Path Arguments
Parameter Data Type Description
token required string The verification email token.

Email Template Object

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

Sample Email Template object

{
    "bcc_addresses": "jsmith@freeconferencecall.com",
    "cc_addresses": null,
    "from_address": "noreply@carrierx.com",
    "html_body": "",
    "name": "Forgot Partner Password template",
    "subject": "QA: CarrierX Password Reset",
    "template_sid": "465eb46b-05a7-4251-b89c-e99f2b81509b",
    "text_body": "To complete your password reset, please click the link below:\n${base_url}?token=${uuid}\n\nYou are receiving this email because someone has initiated a password reset on\nyour account.\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
    "to_addresses": null,
    "type": "forgot_partner_password"
}
Attribute Data Type Description
bcc_addresses read only string The addresses of the recipients to appear in the BCC field.
cc_addresses read only string The addresses of the recipients to appear in the CC field.
from_address read only string The address showing the email sender.
html_body read only string The email HTML body.
name read only string The name of the email template.
subject read only string The email subject title.
template_sid read only string The email template secure ID.
text_body read only string The email text body.
to_addresses read only string The addresses of the recipients.
type read only string The email template type. Values accepted in this field are:
  • email_address_verification for the template used for email verification.
  • email_partner_review for the template used to review partners.
  • forgot_partner_password for the template used to reset the forgotten password.
  • invoice for the invoice template.
  • low_balance_partner_notification for the template used to notify of a low balance.
  • new_partner_welcome for the welcome email message template.
  • suspended_partner_notification for the template used to notify the partner about suspension from access to CarrierX services.

Get Email Templates

GET /verification/email/templates
Returns email templates matching the criteria in the request URL

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

Response 200 status code with a list of Email Template objects

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

This request returns the list of existing email templates.

GET /verification/email/templates

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

Required Scopes

To get information about email templates, the partner must have one of the following scopes enabled:

Get Email Template by SID

GET /verification/email/templates/{template_sid}
Returns an email template, targeted by secure ID

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

Response 200 status code with a serialized copy of the Email Template object

{
    "bcc_addresses": "jsmith@freeconferencecall.com",
    "cc_addresses": null,
    "from_address": "noreply@carrierx.com",
    "name": "Forgot Partner Password template",
    "subject": "QA: CarrierX Password Reset",
    "template_sid": "465eb46b-05a7-4251-b89c-e99f2b81509b",
    "text_body": "To complete your password reset, please click the link below:\n${base_url}?token=${uuid}\n\nYou are receiving this email because someone has initiated a password reset on\nyour account.\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
    "to_addresses": null,
    "type": "forgot_partner_password"
}

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

GET /verification/email/templates/{template_sid}

This request is enabled for Field Filtering.

Required Scopes

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

Path Arguments
Parameter Data Type Description
template_sid required string The template secure ID.