Programmable Voice

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.

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:

Bearer token, used by the requests to the Core API.
Basic HTTP authentication with login and password, used by the requests to the endpoint APIs (Conference, FlexML, and Mediator).

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.

Note that at this time, you can only use tokens for the Core API. Each of the application endpoints has different login and password values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the unauthorized error.

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:

The request URL to which the request will be sent. The URL will be different for the Core API methods and for the main endpoint-related requests (conference, FlexML, mediator).
The request method or the verb used for the REST over HTTP request.
One or several headers or user/password authentication.
- At least one header—-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'—is required to access the Core API.
- For the requests to the conference, FlexML, or mediator endpoints, CarrierX uses the basic HTTP authentication with login and password (cURL -u option).
Refer to the Authentication section for more details on this.

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

Other request may have additional structure elements which include:

Path arguments are required with some methods to access specific objects (GET the object by secure ID, PATCH/PUT, and DELETE objects).
Body payload is required with POST and PATCH/PUT. Even if the object method does not require any body arguments (e.g., POST for some objects), the payload must still include an empty object (--data-binary '{}').

If the request includes body payload, you must use the Content-Type: application/json header with it. Otherwise it will return the 415 Unsupported media type error status code.
Query arguments may be either optional or required for some requests. Refer to the objects sections below to see which object methods require the presence of the query arguments. The optional query arguments available with some GET requests include pagination, result filtering, and field filtering.
Form data is required with some POST methods, e.g., uploading a file to the container using multipart/form-data content type.

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

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

Request Methods

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

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

POST

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:

If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the PATCH request. The other nested object records will remain unmodified.
If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.
If the existing nested object contains the same record and the value of the incoming record is null, then the existing record will be removed. The other nested object records will remain unmodified.
If the PATCH request contains nested_objects=replace as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).

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

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

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

DELETE

Sample DELETE request that deletes an endpoint

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

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

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

Rate Limiting

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

Responses

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

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

HTTP Status Codes

Typical 200 status code in the response

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

The Core API uses the following HTTP status codes:

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

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

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

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

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

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

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

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

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

The above status codes are common for all requests.

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

Response Objects

Typical formatted JSON object in the response

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

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

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

With jq, the request will look like this:

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

Pagination

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

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

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

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

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

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

The pagination parameters include:

limit

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

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

order

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

attribute name + asc to sort the items in the response in the ascending or alphabetical order (default order).
attribute name + desc to sort the items in the response in the descending or reverse-alphabetical order.
shuffle to randomize the order of the items in the response.

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.

The offset parameter is not used together with the after/ before arguments.

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.

If you use the after or before query arguments:

the response pagination attribute will also include the secure IDs of the previous or next objects instead of the offset value;
you cannot set the offset to any value except 0 (normally, you should omit the offset query attribute from such requests);
you can only apply the sorting by the limited number of the object attributes (e.g., date_stop for Call Detail Record objects or date_insert for SMS Detail Record objects).

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`

Refer to our Call Detail Record Application Quick Start to learn more about how you can use the after and before pagination query arguments.

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

limit, offset, order: https://api.carrierx.com/core/v2/countries?limit=2&offset=2&order=common_name+desc
after, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?after=bb2aacd2-23d3-418e-9ec0-2fc45c5f9d76&limit=1&order=date_stop+asc
before, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?before=56fb6b94-811e-4952-b242-4e06f4e95b7e&limit=1&order=date_stop+desc
after, before, limit, order: https://api.carrierx.com/core/v2/sms/message_drs?after=012e1d6a-75ac-43ec-bacc-68f1ef1c60a3&before=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=100&order=date_insert+desc

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

You can use the URLs present in the response pagination attribute to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL(s) provided in this field.

Result Filtering

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

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

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

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

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

Result Filtering Quick Reference

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

For the ilike and like filters, % can be added anywhere as part of the string to indicate that any number of characters can exist in place of %. So, this method of search will also work: name like A%t. This search will yield records with name values beginning with A and ending in t.

Field Filtering

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

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

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

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

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

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

include_fields and exclude_fields accept comma-separated strings as values.

Field Filtering Quick Reference

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

Core Concepts

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

Batch Operations

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

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

Callbacks

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

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

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

sms and callback_url Callback

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

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

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

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

app_mediator Callback

The app_mediator callback response

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

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

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

Call Routing

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

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

Call Routing

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

Third-Party Routing

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

Transformations

Transformations look like the following

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

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

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

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

action is what type of modification will be made. For example, rewrite_to rewrites the destination phone number.
direction determines to which direction of traffic the transformation will apply. For example, if we set direction to outbound, the specific transformation will apply to sending voice calls only.
operands are the items that are being acted upon. For example, rewrite_to accepts two operands: the value to replace and the value that it is going to be replaced with.

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

Attribute	Data Type	Description
action	string	The action to be executed for the transformation. 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.

The fourth (arg1) and up operands will be the arguments for another transformation. E.g., if the transformation selected is reject, then the only argument for it will be the reject reason, thus the total number of operands will be equal to four; if the transformation selected is lookup_rn, then you will need to add nine arguments for it, thus the total number of operands will be twelve.

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.

Only the reason operand is required. The message operand can be omitted. No message will be returned to the caller in this case.

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.

Any headers added would still need to be in the legB SIP_RELAY_HEADERS to be sent to the destination endpoint.

set_header_parameter

Sample set_header_parameter transformation

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

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

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

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

set_user_data

Sample set_user_data transformation

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

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

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

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

stir_validate

Sample stir_validate transformation

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

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

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

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

API Reference

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

Access Control

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

Access Control List Object

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

Sample Access Control List object

{
    "access_control_rules": [
        "dafd993d-0e99-4af9-b8fc-436fb01b0bbe",
        "6fd782fa-c80b-4299-9b91-78797eb392e1"
    ],
    "direction": "outbound",
    "sms_action_false": null,
    "sms_action_true": null,
    "voice_action_false": null,
    "voice_action_true": "reject503"
}

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

Look Up Effective ACLs for Calls

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

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

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

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

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

GET

/accesscontrol/effective_acl/calls

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

Required Scopes

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

accesscontrol.manage
accesscontrol.read

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:

accesscontrol.manage
accesscontrol.read

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

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

POST

/accesscontrol/rules

Required Scopes

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

accesscontrol.manage
accesscontrol.create

Body Arguments

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

Required fields to create an access control rule are:

entries
field
operation
quantifier

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

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

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

Get Access Control Rules

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:

accesscontrol.manage
accesscontrol.read

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:

accesscontrol.manage
accesscontrol.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

accesscontrol.manage
accesscontrol.update

Path Arguments

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:

entries
field
name
operation
quantifier

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

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:

accesscontrol.manage
accesscontrol.delete

Path Arguments

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

Batch

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

Task Object

This section describes the elements of the batch task object.

Sample Task object

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

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

Error Detail Object

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

status

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

Create Task

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

POST

/batch/tasks

Required Scopes

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

batch.manage
batch.create

Body Arguments

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

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

“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:

batch.manage
batch.read

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}

Required Scopes

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

batch.manage
batch.read

Path Arguments

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

batch.manage
batch.update

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.manage
batch.delete

Batch Review

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

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

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

Batch Review Response Object

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

Batch Review Item Object

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

Get Task Review Items by SID

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

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

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

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

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

GET

/batch/tasks/{task_sid}/review_items

Required Scopes

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

batch.manage
batch.read

Path Arguments

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:

batch.manage
batch.read

Path Arguments

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

Calls

Calls are communications between two or more phone numbers.

Call Detail Record Object

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

Sample Call Detail Record object

{
    "cic": null,
    "cic_original": null,
    "cic_transformed": null,
    "date_insert": "2019-01-18T15:35:03.000Z",
    "date_start": "2019-01-18T15:32:15.589Z",
    "date_stop": "2019-01-18T15:32:19.839Z",
    "date_talk": "2019-01-18T15:32:16.535Z",
    "direction": "inbound",
    "disconnect_originator": "DST",
    "diversion_dst": "+15162065451",
    "diversion_src": "+15162065451",
    "dr_sid": "c02a73b2-8401-459a-af7e-f4cc3eee7854",
    "duration": "4.25015",
    "duration_billing": "60",
    "endpoint_sid_dst": "1ce5a6da-7d72-448a-ab81-897fe24b8f02",
    "endpoint_sid_src": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
    "identity": null,
    "ip_dst": "10.222.2.197:5060",
    "ip_src": "162.251.180.18",
    "number_billing": "15162065451",
    "number_dst": "15162065451",
    "number_dst_original": null,
    "number_dst_transformed": null,
    "number_external": "15012678830",
    "number_src": "+15012678830",
    "number_src_original": null,
    "number_src_transformed": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "price": "0.0025",
    "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_stop` – `date_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.

If used with after or before pagination, you can sort the response results by the Call Detail Record object date_stop attribute only (order=date_stop+asc or order=date_stop+desc).

Required Scopes

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

calls.manage
calls.read

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:

calls.manage
calls.read

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:

countries.manage
countries.read

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:

countries.manage
countries.read

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:

countries.manage & lookup.ip_addresses.read
countries.read & lookup.ip_addresses.read

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

POST /endpoints
Creates an endpoint
Conference endpoint

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

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

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

Third-party endpoint

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

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

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

This request creates an endpoint.

POST

/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:

endpoints.manage
endpoints.create

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:

endpoints.manage
endpoints.read

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:

endpoints.manage
endpoints.read

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.

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

The Endpoint object also contains nested Addresses, Attributes, Properties, and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.
A PUT request can be used to update an entire Endpoint object. The endpoint secure ID is passed in the query URL, and the entire Endpoint object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

endpoints.manage
endpoints.update

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.

Note that for the Mediator, FlexML, and Conference endpoints, only the name and capacity fields can be updated.

For the Voicemail endpoint, the properties.callback_method, properties.callback_url, properties.container_sid, and properties.greeting can also be updated. Refer to the Voicemail Endpoint Quick Start Guide for more information on how to create and configure Voicemail endpoint.

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:

endpoints.manage
endpoints.delete

Path Arguments

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

Invoices

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

Invoice Object

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

Sample Invoice object

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

Attribute	Data Type	Description
amount *read only*	number	The amount on the invoice. This is not necessarily due at this time.
amount_due *read only*	number	The amount due.
amount_tax *read only*	number	The tax amount due.
balance_forward *read only*	number	The balance that will be used as `balance_previous` for the next invoice.
balance_previous *read only*	number	The previous balance on the invoice.
date_billing_period_end *read only*	string	The date and time when the billing period ends.
date_billing_period_start *read only*	string	The date and time when the billing period begins.
date_charge_expected *read only*	string	The date and time when the invoice will be charged.
date_charged *read only*	string	The date and time when the invoice was charged.
date_created *read only*	string	The date and time when the invoice was created.
date_issued *read only*	string	The date and time when the invoice was issued.
display_id *read only*	string	The ID on the rendered invoice.
invoice_items *read only*	array	The details about each of the invoice items. Refer to the table below for more information.
invoice_sid *read only*	string	The invoice secure ID.
paid *read only*	boolean	Shows if the invoice has been paid. Values accepted in this field are: `true` and `false`.
partner *read only*	object	The Partner object associated with the invoice. This field is displayed if `with_related` is set to `true` when performing the `GET` queries.
partner_sid *read only*	string	The secure ID of the partner associated with the invoice.
pay_items *read only*	array of objects	The payments made while the invoice was open. Refer to the table below for more information.
status *read only*	string	The invoice status. Values accepted in this field are: `charging` for an invoice that is being charged. `complete` for an invoice that has been charged. `created` for an invoice that has been created. `declined` for an invoice that belongs to a partner without a billing method on file, or an invoice with a payment declined. `error` for a billing module received an error while processing the invoice; invoice may need to be processed manually. `open` for an open invoice. `pending` for an invoice that belongs to a partner with a billing method of check on file; this indicates that a check is anticipated. `reviewing` for an invoice that is awaiting manual approval. `uncollectable` for an invoice that will not be paid.
tax_items *read only*	array of objects	The tax items details. Refer to the table below for more information.

Invoice Item Object

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

Invoice Pay Item Object

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

Invoice Tax Item Object

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

Get Invoices

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

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

Response 200 status code with a list of Invoice objects

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

This request returns a list of invoices.

GET

/invoices

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

Required Scopes

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

invoices.manage
invoices.read

Query Arguments

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

Get Invoice by SID

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

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

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

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

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

GET

/invoices/{invoice_sid}

This request is enabled for Field Filtering.

Required Scopes

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

invoices.manage
invoices.read

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:

invoices.manage
invoices.read

Path Arguments

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

Send Invoice HTML Report by SID to Email Addresses

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

POST

/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:

invoices.manage
invoices.read

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.

In the URL encoded addresses, the @ character is replaced with the %40 sequence of characters, the commas are replaced with %2C, etc.

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:

invoices.manage
invoices.read

Path Arguments

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

Send Invoice PDF Report by SID to Email Addresses

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

POST

/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:

invoices.manage
invoices.read

Path Arguments

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

Body Arguments

In the URL encoded addresses, the @ character is replaced with the %40 sequence of characters, the commas are replaced with %2C, etc.

Lookup

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

Phonenumber Lookup Object

Sample Phonenumber Lookup object

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

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

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

Phonenumber Lookup Detail Object

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

Phonenumber Lookup Detail Carrier Object

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

Phonenumber Lookup Detail Cnam Object

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

Get Details for Phone Number

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

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

Response 200 status code with the phone number details

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

This request returns data for the specified phone number.

GET

/lookup/dids/{phonenumber}

This request is enabled for Field Filtering.

Required Scopes

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

lookup.dids.read to send requests and lookup general information about phone numbers,
lookup.dids.allow_carrier to query detailed information about the carrier (using the carrier query argument set to true),
lookup.dids.allow_cnam to query detailed information about the CNAM (using the cnam query argument set to true),
lookup.dids.allow_lrn to query information about the location routing number (using the lrn query argument set to true).

Path Arguments

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

Query Arguments

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

Phone Number Lookup Logic

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

If the queried number is prefixed with +, the system will check for a full E.164 match only.
- If there is a match, the system will return this match.
- Otherwise, it will return the 400 status code.
When the country_code query parameter is passed, the system checks if the number passed could be valid in the country specified in the request (either the in-country format or by international prefix).
- If the number is valid against the specified country, the system returns this value immediately, no further checks are made.
If no country_code query parameter was passed or if the match did not succeed, the system will check if it is both a valid NANP number (a 10-digit number + a valid NPA) and if it is a valid E.164 number (the prefix matches a valid country code).
- If the number is only a valid NANP number or only a valid E.164 number, this match is returned.
- Otherwise, the system will make a guess. The guess query parameter parameter helps choose between the NANP match and the E.164 match. The default value of north_america will prefer the NANP number.

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

IP2Location Object

Sample IP2Location object

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

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

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

Get Details for IP Address

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

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

Response 200 status code with the IP address details

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

This request returns data for the specified IP address.

GET

/lookup/lookup/ip_addresses/{ip_address}

This request is enabled for Field Filtering.

Required Scopes

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

lookup.ip_addresses.read

Path Arguments

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

OAuth

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

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

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

OAuth Token Object

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

Sample OAuth Token object

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

Attribute	Data Type	Description
access_token *read only*	string	The access token value to be used in authentication.
client_id *read only*	string	The client ID. This is a unique string representing the registration information provided to the client upon request.
client_secret *read only*	string	The client secret string. This is a unique string representing the registration information provided to the client upon request. This field is hidden and not returned in the response.
date_created *read only*	string	The date and time when the token was created.
date_expiration_access_token create update	string	The date and time when the token expires.
date_expiration_refresh_token create update	string	The date and time when the refresh token expires.
date_last_accessed *read only*	string	The date and time when the token was last accessed.
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

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

POST

/oauth/token

Required Scopes

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

oauth.manage_all_tokens
oauth.manage
oauth.create

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

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

POST

/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:

oauth.manage_all_tokens
oauth.manage
oauth.create

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

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

POST

/oauth/revoke

Required Scopes

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

oauth.manage_all_tokens
oauth.manage

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:

oauth.manage_all_tokens
oauth.manage
oauth.read

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:

oauth.manage_all_tokens
oauth.manage
oauth.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

oauth.manage_all_tokens
oauth.manage
oauth.update

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:

date_expiration_access_token
date_expiration_refresh_token
name
scopes

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.

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.

POST /oauth/logins
Creates a partner sub-login

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

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

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

This request creates an additional login for a partner.

POST

/oauth/logins

Required Scopes

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

oauth.manage
oauth.create

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:

login
password
token_scopes

The login attribute has the following naming conventions:

the first part must contain the current partner login to the system (<partner.login>);
the second part contains the sub-login used as additional login to the system (<sub-login>);
the two parts must be separated with the underscore.

Thus, the login attribute value must look like the following:

<partner.login>_<sub-login> (e.g., carrierx_sublogin)

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:

oauth.manage
oauth.read

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

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

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

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

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

GET

/oauth/logins/{login_sid}

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:

oauth.manage
oauth.read

Path Arguments

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

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

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

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

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

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

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

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

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

oauth.manage
oauth.update

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 /oauth/logins/{login_sid}
Deletes a partner login, targeted by secure ID

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

Response 204 status code with an empty body

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

DELETE

/oauth/logins/{login_sid}

Required Scopes

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

oauth.manage
oauth.delete

Path Arguments

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

Partners

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

Partner Object

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

Sample Partner object

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

Attribute	Data Type	Description
acls create update	array of objects	The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information.
address1 create update	string	The partner address.
address2 create update	string	The partner address second field.
attributes create update	object	The partner attributes.
available_scopes *read only*	array	The abilities that this specific partner has. This field is for internal use only. Refer to this table for the complete list of available scopes.
balance *read only*	number	The current balance of the partner.
billing_email create update	string	The partner email address used for billing purposes. If this field is empty, the `owner_email` is used.
callbacks create update	object	The callback URLs. The allowed callback URL types include: `app_conference_call` for conference call activity. `app_conference_meeting` for conference meeting room activity. `app_mediator` for the activity triggered by Mediator endpoint. `sms` for text message activity (when an SMS is sent or received).
charge_at create update	number	The balance value when the prepay account will be charged.
city create update	string	The partner city.
company_name create update	string	The partner company name.
country_code create update	string	The partner country ISO 3166-1 alpha-3 code.
date_created *read only*	string	The date and time when the partner was created.
display_id *read only*	string	The partner unique ID.
login create	string	The login for web and Core API.
name create update	string	The partner name.
owner_email create update	string	The partner primary email address.
parent_assigned_acls create update	array of objects	The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information.
parent_sid create update	string	The parent partner secure ID.
partner_sid *read only*	string	The partner secure ID.
password create update	string	The partner password for web and Core API. This field is required to create a partner, but is hidden in the serialized copy of the Partner objects received in responses to the requests for the security reasons.
payment_type create	string	The type of payment. Values accepted in this field are `prepay` and `postpay`. Note that the default value is `prepay`. To change the `payment_type`, contact technical support at support@carrierx.com.
phonenumber create update	string	The partner contact phone number.
prepay_amount create update	number	The charge amount for prepay customers.
spending_limit create	number	The maximum amount that a partner is allowed to spend on the account.
state create update	string	The partner state; two-letter abbreviation code.
status *read only*	string	The status of the partner. Values accepted in this field are: `active` for a partner account that is active. `canceled` for a partner account that was canceled. `deleted` for a partner account that was removed. `suspended` for a partner account that has been suspended because balance went lower than acceptable limit. `unconfirmed` for a partner account that has not been confirmed. `unverified` for a partner account with an email that has not been verified.
tech_email create update	string	The partner email address used for technical purposes. If this field is empty, the `owner_email` is used.
transformations create update	array of objects	The list of transformations that a call will undergo. Refer to the transformations section for more information.
zip create update	string	The partner zip code.

ACL Object

This object is used with acls and parent_assigned_acls.

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

Create Partner

POST /partners
Creates a partner

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

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

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

This request creates a partner.

POST

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

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

Required Scopes

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

partners.manage
partners.create

Body Arguments

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

Required fields to create a partner are:

charge_at
company_name
country_code
login
owner_email
password
payment_type
phonenumber
prepay_amount
zip

Note that the login value must be unique.

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

Get Partners

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

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

Response 200 status code with a list of Partner objects

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

This request returns a list of partners.

GET

/partners

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:

partners.manage
partners.read

Get Partner by SID

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

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

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

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

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

GET

/partners/{partner_sid}

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:

partners.manage
partners.read

Path Arguments

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

Update Partner

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

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

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

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

This request updates a partner, targeted by secure ID.

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

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

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

The Partner object also contains nested ACLs, Attributes, Callbacks, Parent Assigned ACLs, and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.
A PUT request can be used to update an entire Partner object. The partner secure ID is passed in the query URL, and the entire Partner object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

partners.manage
partners.update

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:

partners.manage
partners.delete

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

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

POST

/partners/{partner_sid}/billing_method

Note that the cc_number value will be redacted as the last four integers in the response.

Required Scopes

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

partners.billing_method.manage
partners.billing_method.create

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:

address1 (for check, electronic_check, and wire billing methods)
cc_cid (for credit card billing methods)
cc_expiration (for credit card billing methods)
cc_number (for credit card billing methods)
city (for check, electronic_check, and wire billing methods)
country_code
first_name
last_name
phone
type
zip

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:

partners.billing_method.manage
partners.billing_method.read

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:

partners.billing_method.manage
partners.billing_method.delete

Path Arguments

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

Phone Numbers

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

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

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

Short codes are short phone numbers used for SMS communications.

DID Object

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

Sample DID object

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "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",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

Attribute	Data Type	Description
attributes create update	object	The DID attributes.
callback_url create update	string	The callback URL to receive events for SMS.
capabilities *read only*	integer	This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability: `1` for receiving SMS `2` for sending SMS `4` for voice `8` for receiving MMS `16` for sending MMS To enable receiving SMS and voice, add `1` and `4` together to make `5`. The maximum value for this field is `31` (`1` + `2` + `4` + `8` + `16`) for all capabilities: SMS (receiving and sending), voice, and MMS (receiving and sending).
classification_sid *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, which this DID belongs to.
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.
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

POST /phonenumber/dids
Assigns a DID to a partner

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

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

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "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",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request assigns a DID to a partner.

POST

/phonenumber/dids

Required Scopes

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

phonenumber.manage
phonenumber.create

Body Arguments

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

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

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

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

Query Arguments

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

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

Get DIDs

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

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

Response 200 status code with a list of DID objects

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "attributes": {},
            "callback_url": null,
            "capabilities": 7,
            "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",
            "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:

phonenumber.manage
phonenumber.read

Query Arguments

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

Get DID by SID

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

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

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

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "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",
    "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:

phonenumber.manage
phonenumber.read

Path Arguments

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

Query Arguments

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

Update DID

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

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

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

{
    "attributes": {
        "name": "main line"
    },
    "callback_url": null,
    "capabilities": 7,
    "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",
    "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.

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

The DID object also contains nested Attributes and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.
A PUT request can be used to update an entire DID object. The DID secure ID is passed in the query URL, and the entire DID object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.manage
phonenumber.update

Path Arguments

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

Query Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

attributes
callback_url
did_group_sid
name
string_key_1
string_key_2
transformations
trunk_group_sid

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

Release DID

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

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

Response 204 status code with an empty body

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

DELETE

/phonenumber/dids/{did_sid}

Required Scopes

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

phonenumber.manage
phonenumber.delete

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": [
        {
            "attributes": {},
            "callback_url": 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",
            "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:

phonenumber.manage
phonenumber.read

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`

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

{
    "attributes": {},
    "callback_url": 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",
    "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:

phonenumber.manage
phonenumber.read

Path Arguments

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

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:

phonenumber.manage
phonenumber.read

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:

phonenumber.manage
phonenumber.read

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 Pagination, Result Filtering, and Field Filtering.

Required Scopes

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

phonenumber.emergency.manage
phonenumber.emergency.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.emergency.manage

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:

phonenumber.emergency.manage

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:

phonenumber.line_information.manage
phonenumber.line_information.read

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.

A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The DID line information secure ID is passed in the query URL, and the values to be modified are passed in the request body.
A PUT request can be used to update an entire DID Line Information object. The DID line information secure ID is passed in the query URL, and the entire DID Line Information object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.line_information.manage

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:

phonenumber.line_information.manage

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

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

POST

/phonenumber/did_groups

Required Scopes

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

phonenumber.manage
phonenumber.create

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:

phonenumber.manage
phonenumber.read

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:

phonenumber.manage
phonenumber.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.manage
phonenumber.update

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:

callback_url
name

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:

phonenumber.manage
phonenumber.delete

Path Arguments

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

Prefix Object

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

Sample Prefix object

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

Attribute	Data Type	Description
attributes create update	object	The prefix attributes.
callback_url create update	string	The callback URL.
lrn_sid *read only*	string	The secure ID of the Location Routing Number, which this prefix belongs to.
name create update	string	The prefix name. The default value is `N/A`.
partner_sid create update	string	The secure ID of the partner associated with the prefix.
prefix create update	string	The prefix that will enable 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

POST /phonenumber/prefixes
Creates a prefix

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

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": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request creates a Prefix object.

POST

/phonenumber/prefixes

Required Scopes

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

phonenumber.manage
phonenumber.create

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": "111111111111111",
            "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
            "string_key_1": null,
            "string_key_2": null,
            "source_trunk_group_sid": null,
            "transformations": [],
            "trunk_group_sid": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of Prefix objects.

GET

/phonenumber/prefixes

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

Required Scopes

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

phonenumber.manage
phonenumber.read

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 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": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

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

GET

/phonenumber/prefixes/{prefix_sid}

This request is enabled for Field Filtering.

Required Scopes

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

phonenumber.manage
phonenumber.read

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 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": "111111111111111",
    "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4",
    "source_trunk_group_sid": null,
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null
}

This request updates a prefix, targeted by secure ID.

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

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

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

The Prefix object also contains nested Attributes and Transformations objects. Refer to this section to learn how nested objects can be updated using the PATCH request.
A PUT request can be used to update an entire Prefix object. The prefix secure ID is passed in the query URL, and the entire Prefix object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.manage
phonenumber.update

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:

attributes
callback_url
name
prefix
source_trunk_group_sid
string_key_1
string_key_2
transformations

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

DELETE

/phonenumber/prefixes/{prefix_sid}

Required Scopes

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

phonenumber.manage
phonenumber.delete

Path Arguments

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

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:

phonenumber.manage
phonenumber.read

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:

phonenumber.manage
phonenumber.read

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, which this short code belongs to.
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:

phonenumber.manage
phonenumber.read

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:

phonenumber.manage
phonenumber.read

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.

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

The Short Code object also contains a nested Attributes object. Refer to this section to learn how nested objects can be updated using the PATCH request.
A PUT request can be used to update an entire Short Code object. The short code secure ID is passed in the query URL, and the entire Short Code object is passed in the request body.

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

phonenumber.manage
phonenumber.update

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:

attributes
callback_url
did_group_sid
name
string_key_1
string_key_2

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:

phonenumber.manage
phonenumber.read

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_p12": "MIINlwIBAzCCDV4...MYzDtWcmbI2AgEB",
    "apns_p12_expiration": "2021-08-19T16:03:25.000Z",
    "apns_p12_password": "myStrongPassword",
    "apns_topic": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": "",
    "google_key": "",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Attribute	Data Type	Description
apns_id create update	string	The Apple Push Messaging Application ID.
apns_p12 create update	string	The Apple Push Notification P12 certificate, encoded to Base64.
apns_p12_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_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

POST /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_p12":"", "apns_p12_password":""}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

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

This request adds an application for sending out push notifications.

POST

/push/applications

Required Scopes

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

push.manage
push.create

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_p12": null,
            "apns_p12_expiration": null,
            "apns_p12_password": null,
            "apns_topic": null,
            "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
            "google_id": null,
            "google_key": null,
            "name": "N/A",
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {},
    "total": null
}

This request returns a list of applications used for sending push notifications to devices.

GET

/push/applications

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

Required Scopes

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

push.manage
push.read

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_p12": null,
    "apns_p12_expiration": null,
    "apns_p12_password": null,
    "apns_topic": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": null,
    "google_key": null,
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

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

GET

/push/applications/{application_sid}

This request is enabled for Field Filtering.

Required Scopes

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

push.manage
push.read

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_p12": null,
    "apns_p12_expiration": null,
    "apns_p12_password": null,
    "apns_topic": null,
    "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc",
    "google_id": null,
    "google_key": null,
    "name": "another name",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

This request updates an application, targeted by secure ID.

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

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

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

push.manage
push.update

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:

apns_id
apns_p12
apns_p12_password
apns_topic
google_id
google_key
name

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:

push.manage
push.delete

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

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

POST

/push/devices

Required Scopes

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

push.manage
push.create

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.

Note that the environment value will be set to production unless otherwise specified.

Required fields to create a device are:

application_sid
token
type

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:

push.manage
push.read

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:

push.manage
push.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

push.manage
push.update

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:

application_version
environment
os_version
token
type

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:

push.manage
push.delete

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

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

POST

/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:

push.manage
push.create

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:

rating.manage
rating.read

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:

rating.manage
rating.read

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:

rating.manage
rating.read

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:

rating.manage
rating.read

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 is expired. Values accepted in this field are: `proxy_pass` to serve the contents of the page directly. `redirect_permanent` to return the permanent redirect status code before redirect. `redirect_temporary` to return the temporary redirect status code before redirect. The default value is `redirect_temporary`.
expired_page create update	string	The content to serve when a link is expired.
expired_status_code create update	integer	The status code to be returned if the `expired_mode` value is `proxy_pass`. Values accepted in this field are: `2xx` to return one of the success status codes. `4xx` to return one of the client error status codes. `5xx` to return one of the server error status codes.
minimum_length create update	integer	The shortest link that the system will create.
not_found_mode create update	string	Determines whether to redirect or serve page contents directly if the link is not found. Values accepted in this field are: `proxy_pass` to serve the contents of the page directly. `redirect_permanent` to return the permanent redirect status code before redirect. `redirect_temporary` to return the temporary redirect status code before redirect. The default value is `redirect_temporary`.
not_found_page create update	string	The content to serve when a link is not found.
not_found_status_code create update	integer	The status code to be returned if the `not_found_mode` value is `proxy_pass`. Values accepted in this field are: `2xx` to return one of the success status codes. `4xx` to return one of the client error status codes. `5xx` to return one of the server error status codes.
partner_sid *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 for this field 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

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

POST

/shortener/domains

Required Scopes

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

shortener.manage
shortener.create

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

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

Body Arguments

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

A required field to create a domain is domain_name.

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

Get Domains

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:

shortener.manage
shortener.read

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:

shortener.manage
shortener.read

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

shortener.manage
shortener.update

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

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

Path Arguments

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

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

domain_name
expired_mode
expired_page
expired_status_code
minimum_length
not_found_mode
not_found_page
not_found_status_code
scope
secure
suffix_pattern

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:

shortener.manage
shortener.delete

Path Arguments

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

Link Object

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

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

Create Link

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

POST

/shortener/links

Required Scopes

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

shortener.manage
shortener.create

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:

destination_url
domain_sid

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

Get Links

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:

shortener.manage
shortener.read

Get Link by SID

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:

shortener.manage
shortener.read

Path Arguments

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

Update Link

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.

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

shortener.manage
shortener.update

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:

destination_url
maximum_ttl
mode
short_name

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

Delete Link

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:

shortener.manage
shortener.delete

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.

Please note that to be able to send or receive messages, the rented phone number must have the appropriate capabilities attribute value set: 1 for receiving SMS, 2 for sending SMS, 8 for receiving MMS, 16 for sending MMS, or 27 for all message capabilities.

SMS Object

This section outlines the SMS object. SMS object is used for both SMS and MMS. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample SMS object

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

Attribute	Data Type	Description
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_did create	string	The phone number that the message will be from, in the E.164 format.
mcc *read only*	integer	The mobile country code.
media_urls create	array	The list of URLs for media resources, if `type` of message is set to `mms`.
message create	string	The message body.
message_segments *read only*	integer	The quantity of 160-symbols segments of an `sms` message. Messages with `type` set to `mms` always consist of a single segment.
message_sid *read only*	string	The message secure ID.
mnc *read only*	integer	The mobile network code.
partner_sid *read only*	string	The secure ID of the partner this message belongs to.
price *read only*	string	The price in US dollars determined for the message to be delivered.
status *read only*	string	The status of the message. Values accepted in this field are: `delivered` - for the messages that have been successfully delivered to the recipient. `failed` - for the messages that failed for some reason. `internal_error` - for the messages that encountered any type of internal system errors while being sent to the recipient. `queued` - for the messages accepted by the system, but not yet sent. `sending_failed` - for the messages that passed through either `internal_error` or `sending_timed_out` status. `sending_timed_out` - for the messages that stuck at the `queued` status for a certain system-set timeout. `sent` - for the messages that were sent to the recipient. `timed_out` - for the messages that have been sent, but then stuck at the `sent` status for a certain system-set timeout. `undelivered` - for the 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_did create	string	The phone number that the message will be delivered to, in the E.164 format.
type create	string	The type of message. Values accepted in this field are `mms` and `sms`. The default value is `sms` if the `media_urls` array is empty, and `mms` if the `media_urls` array contains items.
user_data create update	string	Some additional user-defined data added to the message. The field max length is `2000`.

Send Message

POST /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_did":"15162065575", "to_did":"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_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": null,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": null,
    "status": "queued",
    "to_did": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}

This request sends a message from a rented DID.

POST

/sms/messages

Required Scopes

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

sms.manage
sms.create

Body Arguments

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

Required fields to send a message are:

from_did
media_urls (only required for the mms message type)
message (only required for the sms message type)
to_did

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

sms.manage
sms.read

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

sms.manage
sms.read

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

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

Note, while all fields must be present in a PUT request, not all attributes values may be modified after initial creation.

Required Scopes

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

sms.manage
sms.update

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_insert": "2020-07-24T10:25:11.000Z",
    "date_sent": "2020-07-24T10:25:11.014Z",
    "date_start": "2020-07-24T10:25:11.014Z",
    "date_stop": "2020-07-24T10:25:12.014Z",
    "delay_sent": 0,
    "direction": "outbound",
    "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
    "mcc": 310,
    "media_urls": [
        "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
    ],
    "message": null,
    "message_segments": 1,
    "mnc": 999,
    "number_billing": "15162065870",
    "number_dst": "12078152557",
    "number_external": "12078152557",
    "number_src": "15162065870",
    "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
    "price": "0.005",
    "provider": "tsg",
    "rate": "0.005",
    "status": "sent",
    "type": "mms",
    "user_data": "test_message",
    "version": null
}

Attribute	Data Type	Description
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_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 messages that have been successfully delivered to the recipient. `failed` - for the messages that failed for some reason. `internal_error` - for the messages that encountered any type of internal system errors while being sent to the recipient. `queued` - for the messages accepted by the system, but not yet sent. `sending_failed` - for the messages that passed through either `internal_error` or `sending_timed_out` status. `sending_timed_out` - for the messages that stuck at the `queued` status for a certain system-set timeout. `sent` - for the messages that were sent to the recipient. `timed_out` - for the messages that have been sent, but then stuck at the `sent` status for a certain system-set timeout. `undelivered` - for the 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 accepted in this field are `mms` and `sms`.
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_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [
                "https://storage.carrierx.com/f/cdac0471-f144-42a2-94f8-d9838ce5e4b9"
            ],
            "message": null,
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "mms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit":