Core API Reference Guide




Introduction

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







Using the REST API

This section outlines which credentials are used to work programmatically with the Core API, what types of requests the system recognizes, and the format of the responses. It also holds reference information about Pagination and Filtering.

Credentials

This section provides information about the credentials required to work with the RESTful API programmatically. The credentials used to log into the CarrierX website are the same as those used with working with the Core API. Note that there are separate sets of credentials used for the Conference, FlexML, and Mediator APIs. The Core API credentials can be used to obtain credentials for other application endpoints.

To get a free CarrierX account and gain Core API credentials, provide an email address on the homepage .


Sample Curl Command

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

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

{
  "count": 2,
  "has_more": false,
  "items": [
      {
          "addresses": [
              {
                  "direction": "any",
                  "ip": "10.1.10.69",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
          "name": "System Gateway",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {},
          "transformations": [],
          "type": "system_gateway",
          "voip_token": null
      },
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
          "name": "current_mediator",
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "13e156f7-0d21-4ba6-9e32-c56dc2c6098f",
              "api_url": "https://api.carrierx.com/mediator/v1",
              "login": "sample_mediator_091",
              "password": "LkRO3VOBz0pK"
          },
          "transformations": [],
          "type": "mediator",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 2
}

Requests

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


The Core API has the following base url:

https://api.carrierx.com/core/v2

Note that the system only accepts HTTPS requests, and not HTTP requests.

Responses

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

For a comprehensive list of returned fields for each object, refer to the corresponding Object Reference. These sections outline all of the values that are returned upon a successful request.

Pagination

The four optional parameters for pagination are: offset , limit , order , and filter . These parameters are added to the query URL of GET requests. They inform how many items should be skipped in the response, the amount of records to return, and in what order the results should appear.

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

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

The last parameter of pagination is order . Enter the field name to be ordered followed by the order value, either asc or desc . For example, name desc will return records sorted by name in reverse-alphabetical order. Since the default is asc , entering name by itself will sort the results by name in alphabetical order.

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

Parameters and values for pagination are added to the query URL.

Sample Curl Command

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

Sample JSON Response

{
  "body": {
      "count": 0,
      "has_more": false,
      "items": [],
      "limit": 4,
      "offset": 2,
      "pagination": {
          "previous": "https://api.carrierx.com/mediator/v1/accounts?limit=4&offset=0"
      },
      "total": 1
  },
  "status": 200
}

Pagination Quick Reference

Parameter Data Type Description
filter optional string Use the filter operators to find records according to specific criteria. Please reference the Relational Operator Quick Reference table above in this section for specific definitions and examples.
limit optional integer The number of items to be shown in the response. The value entered should not exceed 1000 . 10 is the default value. This parameter and value are added to the query URL.
offset optional integer The amount of items skipped in the response. 0 is the default value. This parameter and value are added to the query URL.
order optional string The field to be ordered followed by the order value, either asc or desc . Declare the field to be ordered first, and then the order asc or desc . For example: binding_sid desc . This parameter and values are added to the query URL. asc is the default order.


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


Relational Operator Quick Reference

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

Field Filtering

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

Parameters and values for field filtering are added to the query URL.


Sample Curl Command

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

Field Filtering Quick Reference

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




Core Concepts

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

Callbacks

The CarrierX API enables callbacks to be sent to an external URL. When a callback URL is assigned on the DID object or the Partner object, the system sends data about events related to that 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.

Callbacks set on the Partner object level are set as values for the fields sms for SMS messages and app_mediator for mediator endpoints. Callbacks set on the DID level are set as the value of the callback_url field.

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


sms and callback_url Callback

This callback is triggered when an action related to an SMS event occurs.

Attribute Data Type Description
date_created string The date when the SMS message was created.
date_status_changed string The date when the SMS message was last changed.
direction string The direction of the SMS, either inbound or outbound .
from_did string The DID that the SMS came from.
message string The message of the SMS.
message_segments integer The number of segments in the message.
message_sid string The message secure ID.
mnc string The mobile network code.
partner_sid string The partner secure ID.
price string The associated price.
status string The status of the message. Possible values for this field are:
  • created for callback has been created
  • queued for callback is queued
  • sending for callback is sending
  • sent for callback is sent
  • receiving for callback is being received
to_did string The phone number that the SMS went to.

Sample JSON Response

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


app_mediator Callback

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 integer The duration of the call.
endpoint_sid sring 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.

Sample JSON Response

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




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 Reference

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

Attribute Data Type Description
direction string The direction for the Access Control List. Accepted values in this field are: inbound , outbound , and any .
voice_action_true string The action to be executed for calls if any Access Control Rules are applied. Accepted values in this field are: accept , reject403 , and reject503 .
voice_action_false string The action to be executed for calls if no Access Control Rules are applied. Accepted values in this field are: accept , reject403 , and reject503 .
sms_action_true string The action to be executed for SMS messages if any Access Control Rules are applied. Accepted values in this field are accept and reject .
sms_action_false string The action to be executed for SMS messages if no Access Control Rules are applied. Accepted values in this field are accept and reject .
access_control_rules array The list of Access Control Rule secure IDs. See the Access Control Rule Object Reference for more information about Access Control Rules.

Look Up Effective ACLs for Calls

This request returns a list of effective Access Control Lists (ACLs) for the trunk group. Note that effective ACLs are executed from the most top-level object. This request is enabled for Field Filtering .

Method URL
GET /accesscontrol/effective_acl/calls

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/calls' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control List object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Look Up Effective ACLs for SMS

This request returns the list of effective Access Control Lists (ACLs) for the partner or trunk group, targeted by secure ID. Note that effective ACLs are executed from the most top-level object. This request is enabled for Field Filtering .

Method URL
GET /accesscontrol/effective_acl/sms

Patth Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/effective_acl/sms' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control List object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.






Access Control Rule Object Reference

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

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

Create Access Control Rule

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

Method URL
POST /accesscontrol/rules

Body Arguments

Data Type Description
object The fields and values for the new Access Control Rule object. Required fields to create a new object are field , quantifier , entries , and operation . Refer to the Access Control Rule Object Reference section for a list of fields that appear in the Access Control Rule object.

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

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/accesscontrol/rules' \
-H 'Content-Type: application/json' \
--data-binary '{"field":"to", "quantifier":"any", "operation":"prefix","entries": ["1800","1615"]}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control Rule object . Below is a common error that arises when creating a new Access Control Rule. Refer to the HTTP Status Codes section for more common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all the values needed to create a new Access Control Rule were included in the request. The required fields are field , operation , quantifier , and entries .

Get Access Control Rules Matching the Specified Criteria

This request returns a list of Access Control Rules (ACRs) that match the given criteria, and that belong to the currently logged-in partner and parent partner. A partner will not be able to view ACRs created by sub-partners. The read-only field shows whether or not the ACRs belong to the currently logged-in partner.

This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /accesscontrol/rules

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules?offset=0&limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control Rule object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Access Control Rule by SID

This request returns information for a particular Access Control Rule (ACR), targeted by secure ID. Returned ACRs apply to the partner and the parent partner. This request is enabled for Field Filtering .

Method URL
GET /accesscontrol/rules/{rule_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/accesscontrol/rules/dafd993d-0e99-4af9-b8fc-436fb01b0bbe' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control Rule object . Below is a common error that arises when getting an Access Control Rule by secure ID. Refer to the HTTP Status Codes section for more common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Access Control Rule

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

The request below will PATCH an existing ACR. PATCH can be used to add or edit fields and values of an ACR object. Note that read_only must be set to false in order to be able to update an Access Control Rule.

Method URL
PATCH /accesscontrol/rules/{rule_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be modified. To view the fields that appear in the ACR object, see the Access Control Rule Object Reference . Fields that can be changed are:
  • entries
  • field
  • name
  • operation
  • quantifier
  • read-only

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control Rule object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire ACR object. The rule SID is passed in the query URL and the entire ACR object is passed in the request body.

Method URL
PUT /accesscontrol/rules/{rule_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire ACR object with any values to be modified. To view the fields that appear in the ACR object, see the Access Control Rule Object Reference . Fields that can be changed are:
  • entries
  • field
  • name
  • operation
  • quantifier
  • read-only

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-H 'Content-Type: application/json' \
--data-binary '{"entries": ["1800","1615"], "field": "to", "name": "new_name", "operation": "exact", "quantifier": "any", "read_only": false, "rule_sid": "c9109b54-13f2-4157-ba23-2984b3a207dc"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Access Control Rule object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Access Control Rule object are included in the request body.

Delete Access Control Rule

This request deletes an Access Control Rule object, targeted by secure ID. ACRs can only be deleted when associated with the partner. Partners cannot delete an ACR for a parent partner when the value of read-only is true .

Method URL
DELETE /accesscontrol/rules/{rule_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/accesscontrol/rules/c9109b54-13f2-4157-ba23-2984b3a207dc' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.






Calls

Calls are communications between two or more phone numbers.

Call Detail Record Object Reference

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

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

Get Call Detail Records Matching the Specified Criteria

This request returns data about inbound and outbound calls including the date and time, originating and destination phone numbers, and IP addresses of the calling numbers. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /calls/call_drs

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Call Detail Record object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Call Detail Record by SID

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

Method URL
GET /calls/call_drs/{dr_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/call_drs/c02a73b2-8401-459a-af7e-f4cc3eee7854' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Call Detail Record object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID was entered correctly.

Rate Object Reference

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

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

items

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

rates_plan

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

Get Inbound Rates Matching the Specified Criteria

The request returns a list of inbound rates for calls. If a partner_sid is indicated, this request will return all rates for the currently logged-in call initiator. To see the rates of other partners, specify their secure IDs. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /calls/rates/inbound

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "active": "yes",
    "count": 1,
    "effective_date": "2017-10-03T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": null,
            "country_name": null,
            "prefix": null,
            "price": "0.0025"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/calls/rates/inbound?limit=1&offset=1"
    },
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "rates_plan": {
        "name": "voice_inbound_rates-2017-10-15",
        "rates_plan_sid": "6ad7df5d-7603-4d1b-8f5e-223b7dee0c6d"
    },
    "total": 9
}

A successful request will return a 200 response code with a serialized copy of the Rate object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Download CSV with Inbound Rates Matching the Specified Criteria

This request returns a CSV of all inbound rates matching the request criteria. This request is enabled for Field Filtering. Refer to the Using the REST API section for more information. Fields and values for this request are added to the query URL.

Method URL
GET /calls/rates/inbound/csv


Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/inbound/csv' \
-u '[your_user_name]:[your_password]'

This request returns a CSV download. For common errors that get returned, refer to the HTTP Status Codes section.


Get Outbound Rates Matching the Specified Criteria

This request returns a list of outbound rates for calls. If a partner_sid is indicated, the call will return all rates for the currently logged-in call initiator. To see the rates of other partners, specify their secure IDs. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /calls/rates/outbound

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "active": "yes",
    "count": 1,
    "effective_date": "2017-10-30T00:00:00.000Z",
    "has_more": true,
    "items": [
        {
            "billing_increment": "60",
            "billing_minimum": "60",
            "country_code": "USA",
            "country_name": "United States",
            "prefix": "1201200",
            "price": "0.01"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/calls/rates/outbound?limit=1&offset=1"
    },
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "rates_plan": {
        "name": "voice_customer_rates-2017-10-05",
        "rates_plan_sid": "0428d20f-7869-4cf5-aa5c-f44f99a19515"
    },
    "total": 111857
}

A successful request will return a 200 response code with a serialized copy of the Rate object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Download CSV with Inbound Rates Matching the Specified Criteria

This request returns a CSV of all outbound rates matching the request criteria. This request is enabled for Field Filtering. Refer to the Using the REST API section for more information. Fields and values for this request are added to the query URL.

Method URL
GET /calls/rates/outbound/csv


Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/calls/rates/outbound/csv' \
-u '[your_user_name]:[your_password]'

This request returns a CSV download. For common errors that get returned, refer to the HTTP Status Codes section.




Countries

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

Country Object Reference

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

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

Get Countries

This request returns a list of countries. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /countries

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/countries?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Country object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Country by ISO code

This request returns the country associated with an ISO 3166-1 alpha-3 code. This request is enabled for Field Filtering .

Method URL
GET /countries/{country_code}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ITA?exclude_fields=common_name' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Country object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find country by ID Ensure that the country code was entered correctly.

Get Country by IP address

This request returns the country associated with the IP address. This request is enabled for Field Filtering . Contact technical support at support@carrierx.com to enable searching for countries by IP address.

Method URL
GET /countries/ip/{ip_address}

Path Arguments

Parameter Data Type Description
ip_address required string The IPv4 address.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/countries/ip/2.6.26.2' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Country object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
400 Request validation error Ensure that a valid IP address has been added to the request URL.
403 Partner doesn't have permission to use IP address lookup Ensure that the partner account has the proper permission to access this capability. Contact technical support at support@carrierx.com to enable searching for countries by IP 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 PTSN would designate the system_gateway endpoint as the inbound leg. The endpoint being routed to would be listed as the outbound leg. Alernatively, 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 Reference

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

Attribute Data Type Description
addresses object The endpoint addresses. Refer to the table below for more information.
attributes object The endpoint attributes. Refer to the table below for more information.
endpoint_sid string The endpoint secure ID.
voip_token string The endpoint authentication token.
name string The endpoint name.
partner_sid string The secure ID of the partner associated with the endpoint.
capacity integer The maximum number of simultaneous inbound and outbound calls.
type string The type of endpoint. Possible values in this field are:
  • system_gateway for the CarrierX gateway. This endpoint is created automatically when a new partner is created. The endpoint is not modifiable.
  • third_party for third party endpoint
  • conference for hosted conference endpoint
  • mediator for hosted mediator endpoint
  • flexml for hosted flexml endpoint
transformations array The transformations that apply to the endpoint. Refer to the table below for more information.

addresses

Attribute Data Type Description
ip string The IP address.
port integer The port. The default port value is 5060 .
direction string The direction for the address. Values accepted in this field are: inbound , outbound , and any . The default value for this field is any .
tag string The address tag for the trunk. This field cannot be modified and applies to the conference and flexml endpoints.
transport string The protocol for the address. Values accepted in this field are udp and tcp . The default value for this field is udp . This field applies to the mediator endpoint.

attributes

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

transformations

Attribute Data Type Description
direction string The direction for transformation. Accepted values for this field are: inbound , outbound , and any .
action string The action to be executed for transformation. Accepted values for this field are: rewrite_to and rewrite_from .
operands array The values to be used for action .

Create Endpoint

This request creates a new endpoint. For the mediator , conference , and flexml endpoints, only the name and capacity values can be edited after the endpoint has been created.

Method URL
POST /endpoints

Body Arguments

Data Type Description
object The body of the endpoint to be created. Fields required to create a new endpoint are: ip and type . If no value for port is assigned, the value for port will be assigned as 5060 . Refer to the Endpoint Object Reference to see which fields appear in the Endpoint object.

Sample Curl Command: Conference

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response: Conference

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


Sample Curl Command: Third Party

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response: Third Party

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all fields required to create an endpoint were included in the request body.

Get Endpoints Matching the Specified Criteria

This request returns a list of endpoints. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.


Method URL
GET /endpoints

Sample Curl Command

The following curl command filters by IP address.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=addresses.ip+eq+"1.1.2.13"' \
-u '[your_user_name]:[your_password]'

Sample JSON Response: Third Party

{
    "count": 2,
    "has_more": false,
    "items": [
        {
            "addresses": [
                {
                    "direction": "any",
                    "ip": "1.1.2.13",
                    "port": 5060,
                    "transport": "udp"
                }
            ],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac",
            "name": "EP_\u0422_1",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "properties": {},
            "transformations": [],
            "type": "third_party",
            "voip_token": "2c95517b-a5e8-4415-b471-cdd81d5a6dcb"
        },
        {
            "addresses": [
                {
                    "direction": "any",
                    "ip": "1.1.2.13",
                    "port": 5060,
                    "transport": "udp"
                }
            ],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "473d1623-c615-4b43-ab4f-01cd5491c56b",
            "name": "my_third_party",
            "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
            "properties": {},
            "transformations": [],
            "type": "third_party",
            "voip_token": "0cac0ffe-fed4-4ee3-8212-e50659e28088"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 2
}

A successful request will return a 200 response code with a serialized copy of the Endpoint object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Endpoint by SID

This request returns information about an endpoint, targeted by secure ID.


Method URL
GET /endpoints/{endpoint_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints/473d1623-c615-4b43-ab4f-01cd5491c56b' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Endpoint

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

Method URL
PATCH /endpoints/{endpoint_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Note that for mediator, flexml, and conference endpoints, only the name and capacity fields can be updated. Refer to the Endpoint Object Reference for a list of all fields that appear in the Endpoint object.

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Endpoint object. This request can be used to remove, add, and modify values. The endpoint secure ID is passed in the query URL and the entire Endpoint object is passed in the request body.

Method URL
PUT /endpoints/{endpoint_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Endpoint object with any values to be updated. Note that for mediator, flexml, and conference endpoints, only the name and capacity fields can be updated. Refer to the Endpoint Object Reference for a list of all fields that appear in the Endpoint object.

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Content-Type: application/json' \
--data-binary '{"addresses": [{"direction": "any", "ip": "1.1.2.13", "port": 5060, "transport": "udp"}],"attributes": {}, "capacity": 100, "endpoint_sid": "1a34c5e9-3a09-4de5-b553-5f6a9ef202ac", "name": "my_third_party_ep", "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0", "properties": {}, "transformations": [], "type": "third_party", "voip_token": "2c95517b-a5e8-4415-b471-cdd81d5a6dcb"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Endpoint object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Endpoint object are included in the request body.


Delete Endpoint

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

Method URL
DELETE /endpoints/{endpoint_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.





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 Reference

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

Attribute Data Type Description
amount integer The amount of invoice items.
amount_due integer The amount due.
date_created string The date when the invoice was created.
date_charge_expected string The date when the invoice will be charged.
date_charged string The date when the invoice was charged.
invoice_sid string The invoice secure ID.
items string The invoice items. Refer to the table below for more information.
jurisdiction string The invoice tax jurisdiction. Values that appear in this field are:
  • federal
  • state
  • county
  • local
  • unincorporated
  • other
  • state_county_local
  • county_local
paid boolean Shows if the invoice has been paid. Values that appear in this field are: true and false .
partner_sid string The secure ID of the partner associated with the DID.
pay_items string Payments made while the invoide was open. Refer to the table below for more information.
status string The invoice status. Values that appear in this field are:
  • open for open invoice
  • charging
  • pending for invoice that belongs to a partner with billing method of check on file. This indicates that a check is anticipated.
  • declined for invoice that belongs to a partner without a billing method on file, or invoice with payment declined
  • complete for charged invoice.
  • uncollectable
  • error for billing module received an error while processing the invoice. Invoice may need to be processed manually.
tax_items string The invoice tax type. Values that appear in this field are:
  • sales_tax
  • business_and_occupation_tax
  • carrier_gross_receipts
  • district_tax
  • excise_tax
  • federal_excise_tax
  • fed_usf_a_school
  • license_tax
  • puc_fee
  • e911_tax
  • service_tax
  • special_tax
  • state_universal_service_fund
  • statutory_gross_receipts
  • surcharge
  • utility_users_tax
  • sales_web_hosting
  • fed_universal_service_fund
  • state_high_cost_fund
  • state_deaf_and_disabled_fund
  • ca_teleconnect_fund
  • universal_lifeline_telephone_service_charge
  • telecom_relay_surcharge
  • telecommunications_infrastructure
    _maintenance_fee
  • state_poison_control_fund
  • telecommunications_infrastructure_fund
  • ny_mctd_186c
  • ny_mctd_184a
  • franchise_tax
  • utility_users_tax_business
  • fed_telecommunications_relay_service
  • district_tax_residential
  • transit_tax
  • telecommunications_assistance
    _service_fund
  • e911_tax_business
  • trs_business
  • universal_service_fund_access_trunk_line
  • universal_service_fund_business_line
  • e911_tax_pbx_trunk_line
  • license_tax_business
  • optional_telecommunications_infrastructure
    _maintenance_fee
  • sales_tax_business
  • e911_tax_residential

items

Attribute Data Type Description
type string The invoice item status. Values that appear in this field are: telecom , sms , and did .
amount integer The amount of invoice items.
usage integer The usage.
date_created string The date when the invoice was created.
date_billing_period_start string The date when the billing period begins.
date_billing_period_end string The date when the billing period ends.
country_code string The DID country code.

pay_items

Attribute Data Type Description
status string The invoice payment status. Accepted values in this field are declined , complete , and error .
type string The invoice payment type. Accepted values in this field are:
  • credit_card
  • check
  • balance
  • refund_credit_card
  • refund_check
  • charge_back
amount integer The amount of payments.
date_charged string The date when the payment was made.
gateway_order_id string The gateway order ID.
check_number string The check number that was used for payment.
billing_method string The type of the billing method. Accepted values for this field are:
  • american_express
  • visa
  • master_cad
  • discover_card
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number string The credit card number.
cc_expiration string The credit card expiration date in MMyyyy format.
cc_cid string The credit card CID.
ec_account_number string The electronic check account number.
ec_routing_number string The electronic check routing number.
name string The customer name.
address1 string The customer address.
address2 string The customer address second field.
city string The customer city.
state string The customer state in two-letter abbreviation format.
zip string The customer zip code.
country_code string The customer country ISO 3166-1 alpha-3 code.
phone string The customer phone number.

Get Invoices Matching the Specified Criteria

This request returns a list of invoices. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.


Method URL
GET /invoices

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/invoices?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Invoice object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Invoice by SID

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

Method URL
GET /invoices/{invoice_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/invoices/4169705e-4284-482f-8e72-e962a8aaad9d' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Invoice object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Get Invoice HTML Report by SID

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

Method URL
GET /invoices/{invoice_sid}.html

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/invoices/6765ca8a-91c7-4241-98c6-42803de77e74.html' \
-u '[your_user_name]:[your_password]'

This request returns a 200 status code with successful requests, alongside an invoice in HTML format. For common errors that get returned, refer to the HTTP Status Codes section.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.





Lookup

The Lookup API returns data regarding phone numbers. Contact technical support at support@carrierx.com to enable searching for phone number information.

Get Details for Phone Number

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

Method URL
GET /lookup/dids/{phonenumber}

Path Arguments

Parameter Data Type Description
phonenumber required string The phone number to look up.
carrier optional boolean Determines if the carrier information should be shown. Values accepted in this field are true and false .
cnam optional boolean Determines if the cnam information should be shown. Values accepted in this field are true and false .
lrn optional boolean Determines if the local routing number should be shown. Values accepted in this field are true and false .

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/lookup/dids/15162065319?cnam=true&lrn=true&carrier=true' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Response Object

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

carrier

Attribute Data Type Description
type string The type of the DID ("landline")
mcc integer The mobile Country Code.
mnc integer The Mobile Network Code
name string The carrier name.

cnam

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

details

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




OAuth

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

OAuth Object Reference

This section outlines the OAuth token object. The fields listed in the table below will be returned in a JSON object when a successful request has been made. Note that the fields below are returned as objects inside an items array.

Attribute Data Type Description
access_token string The access token string.
token_type string The token type.
refresh_token string The refresh token.
expires_in string The number of seconds during which the token will be valid.
scope string The scope of the access request available for the client.

Revoke Current OAuth Token

This request terminates the current session.

Method URL
POST /oauth/logout

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/logout' \
-H 'Content-Type: application/json' \
-u '[your_user_name]:[your_password]'



Revoke OAuth Token

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

Method URL
POST /oauth/revoke/{token}

Path Arguments

Parameter Data Type Description
token required string The access token.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke/' \
-H 'Content-Type: application/json' \
-u '[your_user_name]:[your_password]'


Get OAuth Bearer Token

This request generates the token for a partner upon request.

Method URL
GET /oauth/token

Path Arguments

Parameter Data Type Description
grant_type required string The grant type for the token.
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.
username required string The login of the partner.
password required string The password of the partner.
scope required string The ccope of the access request available for the client.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token?grant_type=password&client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c&username=carrierx_test&password=carrierx_test_pwd&scope=trust' \
-H 'Content-Type: application/json' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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


Get All Active OAuth Bearer Tokens for the Partner

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

Method URL
GET /oauth/token

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/tokens' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Get Current Partner

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

Method URL
GET /oauth/whoami

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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




Partners

A partner is an individual or company with CarrierX credentials. Partners can have sub-partners, each of which is governed by its own set of credentials. By default, sub-partners cannot be created. Contact technical support at support@carrierx.com to request being able to create sub-partners.

Partner Object Reference

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

Attribute Data Type Description
acls array The Access Control List, as defined on the Partner object directly. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned on the Partner object itself and cannot be assigned by a parent partner. Refer to the table below for more information.
address1 string The partner address.
address2 string The partner address second field.
balance integer The current balance of the partner.
billing_email string The partner email address used for billing purposes. If this field is empty, the owner_email is used.
callbacks string The callback URLs.
charge_at integer The balance value when the prepay account will be charged.
city string The partner city.
company_name string The partner company name.
country_code string The partner country ISO 3166-1 alpha-3 code.
date_created string The date and time when the partner was created.
display_id string The partner unique ID.
login string The login for web and Core API. This field is not modifiable.
name string The partner name.
owner_email string The partner primary email address.
parent_sid string The parent partner secure ID.
parent_assigned_acls array The Access Control List, as defined by a parent partner. This holds a list of rules that determine the scope of data to be checked in SIP calls. This field is assigned by the parent partner only. Refer to the table below for more information.
partner_sid string The partner secure ID.
password string The password for web and Core API. Note that this field is hidden in responses.
payment_type string The type of payment. Possible values accepted in this field are prepay and postpay . Note that the default value is prepay . To change the payment_type , contact technical support at support@carrierx.com .
phonenumber string The partner contact phone number.
prepay_amount integer The charge amount for prepay customers.
status string The status of the partner. Possible values for this field are:
  • deleted for partner was removed
  • active for partner is active
  • canceled for partner is canceled
  • suspended for partner account has been suspended because balance went lower than acceptable limit
  • unverified for partner email has not been verified
  • unconfirmed for partner has not been confirmed
tech_email string The partner email address used for technical purposes. If this field is empty, the owner_email is used.
transformations array The changes that a call will undergo. Refer to the table below for more information.
zip string The partner zip code.

acls

Attribute Data Type Description
direction string The direction for the ACL. Possible values accepted in this field are: inbound , outbound , and any .
voice_action_true string The action to be executed for call if any of Access Control Rules is applied. Possible values accepted in this field are: accept , reject403 , and reject503 .
voice_action_false string The action to be executed for call if none of Access Control Rules is applied. Possible values accepted in this field are: accept , reject403 , and reject503 .
sms_action_true string The action to be executed for sms if any of Access Control Rules is applied. Possible values accepted in this field are: accept and reject .
sms_action_false string The action to be executed for sms if none of Access Control Rules is applied. Possible values accepted in this field are: accept and reject .
access_control_rules array The list of Access Control Rule Secure IDs.

parent_assigned_acls

Attribute Data Type Description
direction string The direction for the ACL. Possible values accepted in this field are: inbound , outbound , and any .
voice_action_true string The action to be executed for call if any of Access Control Rules is applied. Possible values accepted in this field are: accept , reject403 , and reject503 .
voice_action_false string The action to be executed for call if none of Access Control Rules is applied. Possible values accepted in this field are: accept , reject403 , and reject503 .
sms_action_true string The action to be executed for sms if any of Access Control Rules is applied. Possible values accepted in this field are: accept and reject . If this field is set, sms_action_false must be set to null .
sms_action_false string The action to be executed for sms if none of Access Control Rules is applied. Possible values accepted in this field are: accept and reject . If this field is set, sms_action_true must be set to
access_control_rules array The list of Access Control Rule Secure IDs.

transformations

Attribute Data Type Description
direction string The direction for the transformation. Possible values accepted in this field are: inbound , outbound , and any .
action string The action to be executed for the transformation. Possible values accepted in this field are: rewrite_to and rewrite_from .
operands array The values to be used for action .

Create Partner

This request creates a new partner. When a new partner is created, a verification message is sent to the owner_email , tech_email , and billing_email address provided, given that they are different. The email addresses provided will not appear in the Partner object until the link in the email body has been clicked. Confirming the email address allows the partner to use CarrierX services.

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

Method URL
POST /partners

Path Arguments

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

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "balance": "5",
    "billing_email": null,
    "callbacks": {},
    "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"
}


A successful request will return a 200 response code with a serialized copy of the Partner object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the login value is not already associated with a partner account. Also ensure that all of the required fields to create a partner are included in the request body.

Get Partner Matching the Specified Criteria

The request returns a list of partners. Note that email addresses will not appear in the response until they have been verified. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.


Method URL
GET /partners

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/partners' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "acls": [],
            "address1": null,
            "address2": null,
            "attributes": {},
            "balance": "351.52",
            "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": "CX72521509",
            "login": "johnsmith",
            "name": "John Smith",
            "owner_email": "jsmith@freeconferencecall.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": "jsmith@freeconferencecall.com",
            "transformations": [],
            "zip": "90804"
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

A successful request will return a 200 response code with a serialized copy of the Partner object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Partner by SID

This request returns data for a partner, targeted by the secure ID. Note that email addresses will not appear in the response until they have been verified. This request is enabled for Field Filtering .

Method URL
GET /partners/{partner_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "acls": [],
    "address1": null,
    "address2": null,
    "attributes": {},
    "balance": "351.52",
    "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": "CX72521509",
    "login": "johnsmith",
    "name": "John Smith",
    "owner_email": "jsmith@freeconferencecall.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": "jsmith@freeconferencecall.com",
    "transformations": [],
    "zip": "90804"
}

A successful request will return a 200 response code with a serialized copy of the Partner object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Update Partner

A partner can be updated using PATCH and PUT requests. A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request will be updated. All other attributes and values will remain the same. The partner secure ID is passed in the query URL, and the parameters are passed in the request body. This request can be used to update the partner password, partner address, and add or remove acls and transformations .

Method URL
PATCH /partners/{partner_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the Partner Object Reference for a list of all fields that appear in the Endpoint object. Fields that can be changed are:
  • acls
  • address1
  • address2
  • billing_email
  • callbacks
  • city
  • company_name
  • name
  • owner_email
  • parent_assigned_acls
  • phonenumber
  • tech_email
  • transformations
  • zip

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'


Sample JSON Response

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": null,
    "attributes": {},
    "balance": "351.52",
    "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": "CX72521509",
    "login": "johnsmith",
    "name": "John Smith",
    "owner_email": "jsmith@freeconferencecall.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": "15162065574",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "jsmith@freeconferencecall.com",
    "transformations": [],
    "zip": "90804"
}

A successful request will return a 200 response code with a serialized copy of the Partner object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Partner object. This request can be used to remove, add, and modify values. The partner secure ID is passed in the query ID and the body parameters and values are passed in the request body.

Method URL
PUT /partners/{partner_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Partner object and any values to be updated. Refer to the Partner Object Reference for a list of all fields that appear in the Endpoint object. Fields that can be changed are:
  • acls
  • address1
  • address2
  • billing_email
  • callbacks
  • city
  • company_name
  • name
  • owner_email
  • parent_assigned_acls
  • phonenumber
  • tech_email
  • transformations
  • zip

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0' \
-H 'Content-Type: application/json' \
--data-binary '{"acls": [], "address1": "4300 E Pacific Coast Hwy", "address2": "Suite 1", "attributes": {}, "balance": "351.52", "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": "CX72521509", "login": "johnsmith", "name": "John Smith", "owner_email": "jsmith@freeconferencecall.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": "8057224756", "prepay_amount": "100", "spending_limit": "0", "state": null, "status": "active", "tech_email": "jsmith@freeconferencecall.com", "transformations": [], "zip": "90804" }' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "acls": [],
    "address1": "4300 E Pacific Coast Hwy",
    "address2": "Suite 1",
    "attributes": {},
    "balance": "351.52",
    "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": "CX72521509",
    "login": "johnsmith",
    "name": "John Smith",
    "owner_email": "jsmith@freeconferencecall.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": "15162065574",
    "prepay_amount": "100",
    "spending_limit": "0",
    "state": null,
    "status": "active",
    "tech_email": "jsmith@freeconferencecall.com",
    "transformations": [],
    "zip": "90804"
}

A successful request will return a 200 response code with a serialized copy of the Partner object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all the values that appear in the Partner object are included in the request body.

Delete Partner

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

Method URL
DELETE /partners/{partner_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.



Billing Methods

A billing method is how a partner will pay for services rendered.

Billing Method Object Reference

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

Attribute Data Type Description
type string The type of the billing method. Acceptable values in this field are:
  • american_express
  • visa
  • master_card
  • discover_card
  • diners_club
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number string The credit card number.
cc_expiration string The credit card expiration date in mmyyyy format.
cc_cid string The credit card CID.
ec_account_number string The electronic check account number.
ec_routing_number string The electronic check routing number.
name string The customer name.
address1 string The customer address.
address2 string The customer address second field.
city string The customer city.
state string The customer state in two-letter abbreviation format.
zip string The customer zip code.
country_code string The customer country in ISO 3166-1 alpha-3 code.
phone string The customer phone number.

Register Billing Method

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

Method URL
POST /partners/{partner_sid}/billing_method

Path Arguments

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

Body Arguments

Data Type Description
object The body of the billing method to be registered. Refer to the Billing Method Object Reference for a list of the fields that appear in the Billing Method object. The fields needed to create a new billing method are:
  • type
  • cc_number
  • name
  • cc_expiration
  • zip
  • country_code
  • phonenumber

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-H 'Accept: application/json' \
--data-binary '{"type":"visa", "cc_number":"4012888818888", "cc_expiration":"022019", "cc_cid":"318", "first_name":"John", "last_name":"Smith", "address1":"4300 E Pacific Coast Hwy", "address2":"Suite 1", "city":"Los Angeles", "state":"CA", "zip":"90804", "country_code":"USA", "phone":"15162065574"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Billing Method object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all fields required to register a billing method are included in the request body. The fields needed to create a new billing method are type , cc_number , name , cc_expiration , zip , country_code , and phonenumber .

Get Billing Method by Partner SID

This request will return information registered for the selected partner. This request is enabled for Field Filtering .

Method URL
GET /partners/{partner_sid}/billing_method

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Billing Method object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find billing_method for this partner Ensure that the partner secure ID was entered correctly.

Delete Billing Method

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

Method URL
DELETE /partners/{partner_sid}/billing_method

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/partners/ed437757-002d-4ecc-aa5a-efdf5e50dba0/billing_method' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.







Phone Numbers

Phone numbers rentable through the CarrierX API are called DIDs. DIDs can be organized into DID Groups. Refer to Get DID Inventory Matching the Specific Criteria 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 Reference

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

Attribute Data Type Description
did_sid string The DID secure ID.
phonenumber string The phone number for the DID in E.164 format.
in_country_format string The DID in a national format.
international_format string The DID in an international format.
capabilities integer This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability:
  • 1 for inbound SMS
  • 2 for outbound SMS
  • 4 for voice
To enable inbound SMS and voice, add 1 and 4 together to make 5 .
country_code string The ISO 3166-1 alpha-3 code of this DID. This field is assigned automatically.
state string The state or province of the DID.
locality string The locality or city of the DID.
price integer The price of the DID.
partner_sid string The secure ID of the partner associated with the DID.
trunk_group_sid string The secure ID of the trunk group associated with the DID.
callback_url string The callback URL to receive events for SMS.
attributes array The additional attributes.
transformations string The additional attributes. See the table below for more information.

transformations

Attribute Data Type Description
direction string The direction for transformation. Accepted values in this field are: inbound , outbound , and any .
action string The action to be executed for transformation. Accepted values in this field are: rewrite_to and rewrite_from .
operands array The values to be used for action .

Rent DID

This request assigns a DID to a partner account.

Method URL
POST /phonenumber/dids

Body Arguments

Data Type Description
object The body of the DID to be created. A valid and available phonenumber is required to rent a DID. Refer to the DID Object Reference for a list of fields that appear in the DID object. Note that once the phone number has been rented, it must be assigned a trunk group to be usable.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"15162065575", "callback_url":""}'
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "attributes": {},
    "callback_url": null,
    "capabilities": 7,
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
    "in_country_format": "(516) 206-5575",
    "international_format": "+1 516-206-5575",
    "locality": "NEW YORK",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "phonenumber": "15162065575",
    "price": "0.6",
    "state": "NY",
    "transformations": [],
    "trunk_group_sid": null
}

A successful request will return a 200 response code with a serialized copy of the DID object . Below is a common error that arises when getting accounts. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
422 Object validation error Ensure that the DID entered is available for rent.

Get DIDs Matching the Specified Criteria

This request returns a list of DIDs that have been rented. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.


Method URL
GET /phonenumber/dids

Path Arguments

Parameter Data Type Description
trunk_group_sid optional string The trunk group secure ID, used to return DIDs only for a specific trunk group.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
–u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get DID by SID

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

Method URL
GET /phonenumber/dids/{did_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find phonenumber by sid Ensure that the DID secure ID was entered corrected.

Update DID

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

The request below will PATCH an existing DID object. PATCH can be used to add or edit fields and values of a DID object. The DID secure ID is passed in the query URL and the values to be changed are passed in the request body.

Method URL
PATCH /phonenumber/dids/{did_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the DID Object Reference for a list of fields that appear in the DID object. Fields that can be changed are:
  • attributes
  • callback_url
  • did_group_sid
  • name
  • transformations
  • trunk_group_sid

Sample Curl Command

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"}}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire DID object.

Method URL
PUT /phonenumber/dids/{did_sid}

Path Arguments

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

Body Arguments

Parameter Data Type Description
body required object The entire DID object with any values to be updated. Refer to the DID Object Reference for a list of fields that appear in the DID object. Fields that can be changed are:
  • attributes
  • callback_url
  • did_group_sid
  • name
  • transformations
  • trunk_group_sid

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes": {"name": "main line", "new_name":"secondary line"}, "callback_url": null, "capabilities": 7, "country_code": "USA", "did_group_sid": null, "did_sid": "e8df62d5-07a3-4189-a67e-87585067c5fe", "in_country_format": "(516) 206-5574", "international_format": "+1 516-206-5574", "locality": "NEW YORK", "name": "N/A", "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f", "phonenumber": "15162065574", "price": "0.6", "state": "NY","transformations": [], "trunk_group_sid": null}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the DID object are included in the request body.

Delete DID

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

Method URL
DELETE /phonenumber/dids/{did_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/dids/e8df62d5-07a3-4189-a67e-87585067c5fe' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.


DID Group Object Reference

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.

All of the following fields appear in an items object.

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

Create DID Group

This request creates a new DID group.

Method URL
POST /phonenumber/did_groups

Body Arguments

Data Type Description
object The fields and values of the DID group to be created. There are no required fields to create a DID group. Refer to the DID Group Object Reference for a list of fields that appear in the DID Group object.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/did_groups' \
-H 'Content-Type: application/json' \
--data-binary '{}'
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get DID Groups Matching the Specified Criteria

This request returns a list of DID groups. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/did_groups

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/did_groups?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get DID Group by SID

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

Method URL
POST /phonenumber/did_groups/{did_group_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update DID Group

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

Method URL
PATCH /phonenumber/did_groups/{did_group_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the DID Group Object Reference for a list of fields that appear in the DID object. The field that can be updated is name .

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire DID object.

Method URL
PUT /phonenumber/did_groups/{did_group_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire DID Group object with any values to be updated. Refer to the DID Group Object Reference for a list of fields that appear in the DID object. The field that can be updated is name .

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-H 'Content-Type: application/json' \
--data-binary '{"did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c", "name": "renamed_did_group", "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the DID object are included in the request body.

Delete DID Group

This request deletes a DID group.

Method URL
DELETE /phonenumber/did_groups/{did_group_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/did_groups/41e21049-e5eb-433c-a93d-d57417b1863c' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.


Prefix Object Reference

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

Parameter Data Type Description
attributes object The prefix attributes.
callback_url string The callback URL.
partner_sid string The partner secure ID.
prefix string The prefix that will enable routing logic.
prefix_sid string The prefix secure ID.
transformations array The prefix transformations.
trunk_group_sid string The trunk group secure ID.

Create Prefix

This request creates a new Prefix object.

Method URL
POST /phonenumber/prefixes

Body Arguments

Data Type Description
object The body of the Prefix object to be created. Refer to the Prefix Object Reference for a list of fields that appear in the Prefix object. The parameter needed to create a new prefix is prefix .

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/prefixes' \
-H 'Content-Type: application/json' \
--data-binary '{"prefix":"111111111111111"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Prefix object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the prefix field and value are included in the request body.

Get Prefixes Matching the Specified Criteria

This request returns a list of Prefix objects. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/prefixes

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/prefixes' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Prefix object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Prefix by SID

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

Method URL
GET /phonenumber/prefixes/{prefix_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Prefix object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find prefix by SID Ensure that the prefix secure ID is entered correctly.

Update Prefix

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

Method URL
GET /phonenumber/prefixes/{prefix_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the Prefix Object Reference for a list of fields in the Prefix object. Fields that can be changed are:
  • attributes
  • callback_url
  • name
  • prefix
  • transformations

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Prefix object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Prefix object. This request can be used to add, remove, and modify values. The prefix secure ID is passed in the query URL, and the entire Prefix object is passed in the request body.

Method URL
GET /phonenumber/prefixes/{prefix_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Prefix object with any values to be updated. Refer to the Prefix Object Reference for a list of fields in the Prefix object. Fields that can be changed are:
  • attributes
  • callback_url
  • name
  • prefix
  • transformations

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes": {}, "callback_url": null, "name": "newly named main prefix", "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",  "prefix": "111111111111111", "prefix_sid": "cc367acb-94c8-418f-b247-85dce5806ef4", "transformations": [], "trunk_group_sid": null}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Prefix object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Prefix object are included in the request body.

Delete Prefix

This requests deletes a prefix, targeted by secure ID.

Method URL
GET /phonenumber/prefixes/{prefix_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/prefixes/cc367acb-94c8-418f-b247-85dce5806ef4' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.



Short Code Object Reference

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

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

Get Short Codes Matching the Specified Criteria

This request returns a list of Short Code objects. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/short_codes

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/short_codes' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Short Code object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Short Code by SID

This request returns a Short Code object, targeted by secure ID. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/short_codes/{short_code_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Short Code object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Object validation error Ensure that the short code secure ID was entered correctly.

Update Short Code

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

Method URL
PATCH /phonenumber/short_codes/{short_code_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to update. Refer to the Short Code Object Reference for a list of fields that appear in the Short Code object. Fields that can be changed are:
  • attributes
  • callback_url
  • name

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
--data-binary '{"name":"new short code name"}'
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Short Code object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Short Code object.

Method URL
PUT /phonenumber/short_codes/{short_code_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Short Code object including any values to update. Refer to the Short Code Object Reference for a list of fields that appear in the Short Code object. Fields that can be changed are:
  • attributes
  • callback_url
  • name

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
--data-binary '{"attributes": {}, "callback_url": null,  "country_code": "USA", "did_group_sid": "9cf3c0aa-3f80-43f7-b8c2-8f88251ff562", "locality": null, "name": "another name",  "partner_sid": "b9ba2c8b-2368-4a0b-9ba0-866ff2618417", "short_code": "26399", "short_code_sid": "531f65b7-dff7-42b4-b638-597f91da9ccc", "state": "IL" }'
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Short Code object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Short Code object are included in the request body.

Delete Short Code

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

Method URL
DELETE /phonenumber/short_codes/{short_code_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/phonenumber/short_codes/531f65b7-dff7-42b4-b638-597f91da9ccc' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.



Browse Available DIDs Matching the Specified Criteria

This request returns a pool of rentable phone numbers. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.


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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/available_dids?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Browse Coverage Matching the Specified Criteria

This request returns data about available phone numbers rentable through CarrierX. Responses can also include inventory levels. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/coverage

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/coverage?limit=1&group_by=state' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Response Object

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

Get Rates Matching the Specified Criteria

This request returns monthly rental fees for a phone number matching the defined criteria. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/rates?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Response Object

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

Look Up Rates by Phone Number

This request returns rates for a specified phone number. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /phonenumber/rates/{phonenumber}

Path Arguments

Parameter Data Type Description
phonenumber required string The phone number.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/rates/15162065319?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

Response Object

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





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 is created and at least one Device object is associated with it. Messages are sent from applications to devices.

Application Object Reference

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

Attribute Data Type Description
name string The name of the application.
application_sid string The application secure ID.
partner_sid string The partner secure ID.
google_id string The Google Push Messaging Application ID.
google_key string The Google Push Messaging authentication key.
apns_id string The Apple Push Messaging Application ID.
apns_p12 string The Apple Push Notification P12 certificate, encoded to Base64.
apns_p12_password string The passphrase of the Apple Push Notification P12 certificate.

Create Application to Send Push Notifications

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

Method URL
POST /push/applications

Body Arguments

Data Type Description
object The body of the application object to be created. Refer to the Application Object Reference to see which fields appear in the Application object. An empty object can be passed.

Sample Curl Command

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":""}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Application object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Applications Matching the Specified Criteria

This request returns a list of applications used for sending push notifications onto devices. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /push/applications

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/push/applications?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Application object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Application by SID

This request returns data about an application, targeted by secure ID. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /push/applications/{application_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Application object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Application

An Application object can be modified using PATCH and PUT requests. A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request will be updated. All other attributes and values will remain the same. This request is enabled for Field Filtering .

Method URL
PATCH /push/applications/{application_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the Application Object Reference for a list of all fields that appear in the Application object. Fields that can be changed are:
  • name
  • google_id
  • google_key
  • apns_id
  • apns_p12
  • apns_p12_password

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Application object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Application object. This request can be used to add, remove, and modify values. The application secure ID is passed in the query URL, and the body values are passed in the request body.

Method URL
PUT /push/applications/{application_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Application object with any updated values. Refer to the Application Object Reference for a list of all fields that appear in the Application object. Fields that can be changed are:
  • name
  • google_id
  • google_key
  • apns_id
  • apns_p12
  • apns_p12_password

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "new_name", "application_sid": "8b03edc1-5378-4c4e-a480-9015206089dc", "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f", "google_id": "", "google_key": "", "apns_id": "", "apns_p12": null, "apns_p12_password": null}' \
-u '[your_user_name]:[your_password]'


Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Application object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the entire Application object has been added to the request body.

Delete Application

This request deletes an application, targeted by secure ID. Note that deleting an application will remove the device where it has been installed.

Method URL
DELETE /push/appplications/{application_sid}

Path Arguments

Parameter Data Type Description
application_sid required string The secure ID of the application to be deleted.

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/push/applications/8b03edc1-5378-4c4e-a480-9015206089dc' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.


Device Object Reference

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

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

Create Device to Send Push Notifications

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

Method URL
POST /push/devices

Body Arguments

Data Type Description
object The body of the Device object to be created. Refer to the Device Object Reference for a list of all fields that appear in the Device object. Note that the environment value will be set to production unless otherwise specified. Required fields to create a new device are:
  • application_sid
  • type
  • token

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/push/devices' \
-H 'Content-Type: application/json' \
--data-binary '{"application_sid":"b3edc875-f73c-4c48-895a-8697b92b8d07", "type":"ios", "token":"1111", "os_version":"", "application_version":""}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Device object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Devices Matching the Specified Criteria

This request returns a list of applications used for push notifications. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /push/devices

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/push/devices' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Device object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Device by SID

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

Method URL
GET /push/devices/{device_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/push/devices/56d485ae-0693-421a-91eb-6b02b152573a' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Device object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Device

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

Method URL
PATCH /push/devices/{device_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields to be updated. Refer to the Device Object Reference for a list of all fields that exist in the Device object. Fields that can be changed are type and token .

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Device object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire Device object.

Method URL
PUT /push/devices/{device_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Device object with any values to be updated. Refer to the Device Object Reference for a list of all fields that exist in the Device object. Fields that can be changed are type and token .

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/push/devices/0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d' \
-H 'Content-Type: application/json' \
--data-binary '{"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": "222", "type": "android"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "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": "222",
    "type": "android"
}

A successful request will return a 200 response code with a serialized copy of the Device object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Device object are included in the request body.

Delete Device

This request deletes a device, targeted by secure ID.

Method URL
DELETE /push/devices/{device_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/push/devices/56d485ae-0693-421a-91eb-6b02b152573a' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.


Notification Object Reference

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

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

Send Notification

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

Method URL
POST /push/notifications

Body Arguments

Data Type Description
object The body of the Notification object to be created. Refer to the Notification Object Reference for a list of fields that appear in the Notification object. The only field needed to create a new Device object is recipients .

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/push/notifications'
-H 'Content-Type: application/json' \
--data-binary '{"message": {"what":"MEETING_PROPOSAL_DISPATCHED", "data": {"originator_uuid":"1234567890","meeting_id":"123"}}, "ttl": 5, "priority": "normal", "recipients": ["901dd79e-ff4f-4ff3-9b48-c095dfb4fcef", "16e64699-3064-463b-8dc7-96783c08a3d9"]}'' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Notification object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that recipients were added to the request body.





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 Reference

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

Attribute Data Type Description
domain_sid string The domain secure ID.
partner_sid string The secure ID of the partner associated with the domain.
domain_name string The unique domain name.
scope string Determines who can create a link using the domain_sid . Accepted values in this field are self , children , and public .
minimum_length integer The shortest link that the system will create.
not_found_page string The content to serve when a link is not found.
not_found_mode string Determines whether to redirect or serve page contents directly if the link is not found. Accepted values in this field are redirect_temporary and redirect_permanent .
not_found_status_code integer The status code to be returned if not_found_mode is proxy . Values accepted in this field are: 2xx , 4xx , and 5xx .
expired_page string The content to serve when a link is expired.
expired_mode string Determines whether to redirect or serve page contents directly if the link is expired. Accepted values in this field are redirect_temporary and redirect_permanent .
expired_status_code integer The status code to be returned if expired_mode is proxy . Values accepted in this field are: 2xx , 4xx , and 5xx .
secure boolean Determines whether links returned should be prefixed with https . The default value for this field is false .
suffix_pattern string The RegExp of suffixes allowed for partial links by the HTTP server. For example, .(.mp3|mp4) will allow file names ending in .mp3 or .mp4 . By default, the server will not allow suffixes.

Create Domain

This request creates a new Domain object.

Method URL
POST /shortener/domains

Body Arguments

Data Type Description
object The body of the object to be created. Refer to the Domain Object Reference for a list of all fields that appear in the Domain object. The only field required to create a domain is domain_name .

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/shortener/domains' \
-H "Content-Type: application/json" \
--data-binary '{"domain_name":"newdomain.com"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Domain object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that domain_name was added to the request body.

Get Domains Matching the Specified Criteria

This request returns a list of existing domains for the currently logged in partner. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /shortener/domains

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/domains' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Domain object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Domain by SID

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

Method URL
GET /shortener/domains/{domain_sid}

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-u '[your_user_name]:[your_password]'

Path Arguments

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

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Domain object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that domain_name was added to the request body.

Update Domain

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

Method URL
PATCH /shortener/domains/{domain_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the Domain Object Reference for a list of fields that appear in the Domain object. Fields that can be changed are:
  • domain_name
  • scope
  • minimum_length
  • not_found_page
  • not_found_mode
  • not_found_status_code
  • expired_page
  • expired_mode
  • expired_status_code
  • secure
  • suffix_pattern

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

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


A successful request will return a 200 response code with a serialized copy of the Domain object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that a valid URL has been assigned to not_found_page or expired_page .


The PUT request below can be used to update an entire Domain object. The domain secure ID is passed in the query URL and the body parameter is passed in the request body.

Method URL
PUT /shortener/domains/{domain_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Domain object including any values to be updated. Refer to the Domain Object Reference for a list of fields that appear in the Domain object. Fields that can be changed are:
  • domain_name
  • scope
  • minimum_length
  • not_found_page
  • not_found_mode
  • not_found_status_code
  • expired_page
  • expired_mode
  • expired_status_code
  • secure
  • suffix_pattern

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-H "Content-Type: application/json" \
--data-binary '{"domain_name": "mynewwebsite.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}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Domain object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Delete Domain

This request deletes a domain, targeted by secure ID.

Method URL
DELETE /shortener/domains/{domain_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/shortener/domains/a0625551-63de-428e-889d-2d467b4e77a3' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.



Link Object Reference

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

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

Create Link

This request creates a new Link object.

Method URL
POST /shortener/links

Path Arguments

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

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/shortener/links' \
-H "Content-Type: application/json" \
--data-binary '{"domain_sid":"330a8a83-d4bb-4f39-ae54-c59c8d87cd44", "destination_url":"http://destinationurl.com", "maximum_ttl":"-1"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Link object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the domain_sid and destination_url are included in the request body.

Get Links Matching the Specified Criteria

This request returns a list of existing links for the currently logged in partner. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /shortener/links

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/links' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Link object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Link by SID

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

Method URL
GET /shortener/links/{link_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Link object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Link

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

Method URL
PATCH /shortener/links/{link_sid}

Path Arguments

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

Body Arguments

Parameter Data Type Description
body required object The fields and values to be updated. Refer to the Link Object Reference for a list of field that appear in the Link object. Fields that can be changed are:
  • destination_url
  • mode
  • maximum_ttl

Sample Curl Command

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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Link object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Link object. This request can be used to remove, add, and modify values. The link secure ID is passed in the query URL and the body parameters and values are passed in the request body.

Method URL
PUT /shortener/links/{link_sid}

Path Arguments

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

Body Arguments

Parameter Data Type Description
body required object The entire Link object with any values to be updated. Refer to the Link Object Reference for a list of field that appear in the Link object. Fields that can be changed are:
  • destination_url
  • mode
  • maximum_ttl

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
--data-binary '{"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"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Link object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Link object are included in the request body.

Delete Link

This request deletes a link, targeted by secure ID.

Method URL
DELETE /shortener/links/{link_sid}

Path Arguments

Parameter Data Type Description
link_sid required string The secure ID of the link to be deleted.

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/shortener/links/a533f53a-7e6f-4822-be3c-3767924ee2a9' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.








SMS

SMS messages can be sent from rented DIDs. Messages can be queued and sent out successively.

SMS Object Reference

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

Attribute Data Type Description
date_created string The date that the SMS message was created.
date_status_changed string The date that the SMS message status last changed.
direction string The direction of the call or SMS. Values that will appear in this field are inbound for incoming SMS and outbound for outgoing SMS .
from_did string The phone number that the SMS message will be from, in E.164 format.
mcc integer The mobile country code.
message string The message body.
message_segments string The quantity of 160 symbols segments of message.
message_sid string The message secure ID.
mnc integer The mobile network code.
partner_sid string The partner secure ID.
price string The price for the detail record.
status string The status of the message. Possible values that appear in this field are:
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
to_did string The phone number that the SMS message will be delivered to, in E.164 format.

Send SMS Message

This request will send an SMS message from a rented DID.

Method URL
POST /sms/messages

Body Arguments

Data Type Description
object The body of the SMS message to be sent. Refer to the SMS Object Reference for a list of all fields that appear in the Domain object. Fields required to send an SMS message are:
  • from_did
  • message
  • to_did

Sample Curl Command

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"}'
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": null,
    "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"
}

A successful request will return a 200 response code with a serialized copy of the SMS object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the from_did , to_did , and message are included in the request body.

Get SMS Messages Matching the Specified Criteria

This request returns a list of inbound and outbound messages. This request is enabled for Pagination and Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /sms/messages

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/sms/messages?limit=1' \
-u '[your_user_name]:[your_password]'


Sample JSON Response

{
    "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,
            "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"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://api.carrierx.com/core/v2/sms/messages?limit=1&offset=1"
    },
    "total": null
}

A successful request will return a 200 response code with a serialized copy of the SMS object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get SMS Message by SID

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

Method URL
GET /sms/messages/{message_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/sms/messages/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "date_created": "2019-01-18T21:01:13.415Z",
    "date_status_changed": "2019-01-18T10:01:00.000Z",
    "direction": "outbound",
    "from_did": "15162065575",
    "mcc": 0,
    "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"
}

A successful request will return a 200 response code with a serialized copy of the SMS object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Get Outbound Rates Matching the Specified Criteria

This request returns a list of outbound rates for a partner. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.

Method URL
GET /sms/rates/outbound

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/sms/rates/outbound?limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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




Storage

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

Container Object Reference

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

Attribute Data Type Description
allowed_classifications array Any file with a classification not appearing on this list will be rejected. Classification values are:
  • media
  • document
  • executable
  • archive
  • unknown
available_bytes_percent integer The percentage of bytes available.
available_files_percent integer The percentage of files available.
blocked_classifications array Any file with a classification on this list will be rejected. Classification values are:
  • media
  • document
  • executable
  • archive
  • unknown
container_sid string The container secure ID.
durability_class string How the data is stored. At this time, only the default value unassigned is available.
encrypted boolean Whether or not the data is stored on a encrypted disk. The default value for this field is false . Note that this value cannot be changed after the Container object has been created.
name string The container name.
partner_sid string The secure ID of the partner associated with the container.
parent_container_sid string The parent container secure ID. If set, and referenced file no longer exists, the container will be deleted.
quota_files integer The maximum number of files that can be stored in the container.
durability_class string The secure ID of the partner which this Container belongs to.
integer_key_1 integer A user-defined integer key.
integer_key_2 integer A user-defined integer key.
string_key_1 string A user-defined string key.
string_key_2 string A user-defined string key.
total_files integer The maximum number of files that are stored in the container.
total_bytes integer The maximum size in bytes that are stored in the container.
unique boolean Whether or not the container keys must be unique. The default value for this field is false . To avoid errors, this field should be set when the Container object is initially created.

Create Container

This request creates a Container object.

Method URL
POST /storage/containers

Body Arguments

Data Type Description
object The body of the Container object to be created. Refer to the Container Object Reference for a list of all fields that appear in the Container object. There are no fields required to create a container.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/storage/containers' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Container object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Containers Matching the Specified Criteria

This request returns a list of containers that are available for files upload. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /storage/containers

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/storage/containers' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Container object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Container by SID

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

Method URL
GET /storage/containers/{container_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Container object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Container

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

Method URL
PATCH /storage/containers/{container_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the Container Object Reference for a list of fields that appear in the Container object. Fields that can be changed are:
  • allowed_classifications
  • blocked_classifications
  • integer_key_1
  • integer_key_2
  • name
  • string_key_1
  • string_key_2

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-H 'Content-Type: application/json' \
--data-binary '{"integer_key_1":"39984"}' \
-u '[your_user_name]:[your_password]'

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

A successful request will return a 200 response code with a serialized copy of the Container object . Below are some common errors for this request. Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.
422 Object validation error Ensure that the field can be updated.


The PUT request below can be used to update an entire Container object. The container secure ID is passed in the query URL and the entire Container object is passed in the request body.

Method URL
PUT /storage/containers/{container_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Container object with any values to be updated. Refer to the Container Object Reference for a list of fields that appear in the Container object. Fields that can be changed are:
  • allowed_classifications
  • blocked_classifications
  • integer_key_1
  • integer_key_2
  • name
  • string_key_1
  • string_key_2

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-H 'Content-Type: application/json' \
--data-binary '{"allowed_classifications": [], "available_bytes_percent": 100, "available_files_percent": 100, "blocked_classifications": [], "container_sid": "a291fe99-43d6-446f-a63e-91f93030dc7e", "durability_class": "unassigned", "encrypted": false, "integer_key_1": 39984, "integer_key_2": null, "name": "N/A", "parent_container_sid": null, "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f", "quota_bytes": 1073741824, "quota_files": 100, "string_key_1": "for audio usage", "string_key_2": null, "total_bytes": 0, "total_files": 0, "unique": false}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Container object . Below are some common errors for this request. Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.
422 Object validation error Ensure that the field can be updated.
422 Object validation error Ensure that all of the fields that appear in the Container object are included in the request body.

Delete Container

This request deletes a container, targeted by secure ID.

Method URL
DELETE /storage/containers/{container_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/storage/containers/a291fe99-43d6-446f-a63e-91f93030dc7e' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.



File Object Reference

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

Attribute Data Type Description
container_sid string The secure ID of the container which this file belongs to.
content_duration integer The duration of the file. This field cannot be modified.
content_format string The format of the uploaded file. This field cannot be modified.
content_transcoding_progress string The progress of the content transcoding. This field cannot be modified.
date_modified string The date when the last update of the file took place.
desired_format string The desired format for audio and video file. The default value is mp3 . Refer to the table below for all file types supported.
file_access_name string The path to the file within the container. This field defaults to the file secure ID with extension, where possible.
file_bytes integer The file size.
file_sid string The file secure ID.
integer_key_1 integer A user-defined integer key.
integer_key_2 integer A user-defined integer key.
lifecycle_action string The action to be triggered after lifecycle_ttl has elapsed. The only value accepted in this field at this time is delete .
lifecycle_ttl integer How long in seconds before the lifecycle_action will be triggered. -1 means indefinite.
mime_type string The content type of the file.
name string The file name.
parent_sid string The parent file secure ID. Setting a parent_sid forms a folder-like structure. Files can have a parent_sid and this will organize them in groups. If this field is set, and the parent_sid no longer exists, files associated with the this folder-like structure will be deleted.
partner_sid string The secure ID of the partner the file belongs to.
publish string Whether to publicly serve a file, and how to store it. Accepted values in this field are:
  • no to not serve the URL via public HTTP.
  • file_access_name to serve the URL in the following manner: /c/{container_sid}/{file_access_name}
  • file_sid to serve the URL in the following manner: /f/{file_sid}
publish_uri string The web accessible URI where the file can be retrieved. This value is only applicable if publish is set to true .
string_key_1 string A user-defined string key.
string_key_2 string A second user-defined string key.
type string The type of the file. Values accepted in this field are:
  • file which is the default value.
  • audio which verifies the file type, adds appropriate fields, and allows the ability to transcode to another audio format.
  • video which verifies the file type, and acts similarly to the audio type.
  • conference which is less commonly used

desired_format

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


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

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

Upload File

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

Method URL
POST /storage/files

Form Arguments

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

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/storage/files' \
-F 'file_object={"container_sid":"cb05c1f4-2398-432c-8314-cc306156281c"}' \
-F 'data=@4931.mp3' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the File object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that the container_sid is included in the request.

Get Files Matching the Specified Criteria

This request returns a list of files. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /storage/files

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/storage/files' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the File object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get File by SID

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

Method URL
GET /storage/files/{file_sid}

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/storage/files/f6070be2-9abd-4726-870c-c86c9aac5c7e' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the File object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update File

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

Method URL
PATCH /storage/files/{file_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values to be updated. Refer to the File Object Reference for a list of fields that exist in the File object. Fields that can be changed are:
  • integer_key_1
  • integer_key_2
  • lifecycle_action
  • lifecycle_ttl
  • name
  • string_key_1
  • string_key_2

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/core/v2/storage/files/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"new_name"}'' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the File object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire File object. The file secure ID is passed in the query URL and the entire File object is passed in the request body.

Method URL
PUT /storage/files/{file_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire File object and any values to be updated. Refer to the File Object Reference for a list of fields that exist in the File object. Fields that can be changed are:
  • integer_key_1
  • integer_key_2
  • lifecycle_action
  • lifecycle_ttl
  • name
  • string_key_1
  • string_key_2

Sample Curl Command

curl -X PUT 'https://api.carrierx.com/core/v2/storage/files/f6070be2-9abd-4726-870c-c86c9aac5c7e'
-H 'Content-Type: application/json' \
--data-binary '{"container_sid": "cb05c1f4-2398-432c-8314-cc306156281c", "content_classification": "unknown", "content_duration": null, "content_format": "mp3", "content_transcoding_progress": null, "date_modified": "2019-01-22T18:13:30.900Z", "desired_bitrate": null, "desired_format": null, "file_access_name": "f6070be2-9abd-4726-870c-c86c9aac5c7e.mp3",  "file_bytes": 29799, "file_sid": "f6070be2-9abd-4726-870c-c86c9aac5c7e",  "integer_key_1": null, "integer_key_2": null, "lifecycle_action": null, "lifecycle_ttl": -1, "mime_type": "audio/mpeg", "name": "new_name", "parent_file_sid": null, "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f", "publish": "file_sid", "publish_uri": "http://storage-carrierx.com/f/f6070be2-9abd-4726-870c-c86c9aac5c7e", "string_key_1": "this is my string", "string_key_2": "another string", "type": "file", "unique": false }'
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the File object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the File object are included in the request body.

Delete File

This request deletes a file, targeted by secure ID.

Method URL
DELETE /storage/{file_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/storage/files/f6070be2-9abd-4726-870c-c86c9aac5c7e' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.






Trunk Groups

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

Trunk Group Object Reference

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

Attribute Data Type Description
trunk_group_sid string The trunk group secure ID.
name string The trunk group name. If no value is passed at creation, the value assigned will be N/A .
partner_sid string The secure ID of the partner associated with the Trunk Group.
routing_type string The routing type for trunks. Accepted values in this field are failover and round_robin . The default value is failover .
routing_data object The additional routing data for trunks.
soft_failure_cooldown string The time in seconds to wait if the trunk is down.
soft_failure_codes string The SIP codes on the basis of which Trunk failure is defined, separated by ; .
acls object The Access Control Lists associated with the trunk group. Refer to the table below for more information.
transformations object The transformations associated with the trunk group. Refer to the table below for more information.
trunks object The trunks of the trunk group. Refer to the table below for more information.

acls

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

transformations

Attribute Data Type Description
direction string The direction for transformation. Accepted values in this field are: inbound , outbound , and any .
action string The action to be executed for transformation. Accepted values in this field are: rewrite_to and rewrite_from .
operands array The values to be used for action .

trunks

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

Create Trunk Group

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

Method URL
POST /trunks_groups

Path Arguments

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

Body Arguments

Data Type Description
object The body of the trunk group to be created. Refer to the Trunk Group Object Reference for a list of fields that appear in the Trunk Group object. No fields are required to create a trunk group.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true' \
-H 'Content-Type: application/json' \
--data-binary "{"name":"New Trunk Group", "trunks":[{"name": "Trunk1", "endpoint_sid": ""}]}" \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Trunk Groups Matching the Specified Criteria

This request returns a list of Trunk Groups. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.


Method URL
GET /trunk_groups

Path Arguments

Parameter Data Type Description
with_trunks optional boolean Determines whether or not the returned data will include trunk groups with trunks.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&limit=1' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Trunk Group by SID

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

Method URL
GET /trunk_groups/{trunk_group_sid}

Path Arguments

Parameter Data Type Description
trunk_group_sid required string The Trunk Group secure ID.
with_trunks optional boolean Determines whether or not to return Trunk Groups that have one or more Trunks.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0?with_trunks=true" \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Trunk Group

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

Method URL
PATCH /trunk_groups/{trunk_group_sid}

Path Arguments

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

Body Arguments

Data Type Description
objec The fields and values of the Trunk Group object to be updated. Refer to the Trunk Group Object Reference for a list of fields that appear in the Trunk Group object. Fields that can be changed are:
  • name
  • routing_type
  • routing_data
  • soft_failure_cooldown
  • soft_failure_codes
  • acls
  • transformations
  • trunks

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "TrunkGroup4"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



A PUT request can be used to update the entire Trunk Group object. This request can be used to remove, add, and modify values. The trunk group secure ID is passed in the query URL and the body parameters and values are passed in the request body.

Method URL
PUT /trunk_groups/{trunk_group_sid}

Path Arguments

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

Body Arguments

Data Type Description
objec The entire Trunk Group object with any values to be updated. Refer to the Trunk Group Object Reference for a list of fields that appear in the Trunk Group object. Fields that can be changed are:
  • name
  • routing_type
  • routing_data
  • soft_failure_cooldown
  • soft_failure_codes
  • acls
  • transformations
  • trunks

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-H 'Content-Type: application/json' \
--data-binary '{"acls": [], "name": "my_trunk_group", "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0", "routing_data": null, "routing_type": "failover", "soft_failure_codes": "408;", "soft_failure_cooldown": 120, "transformations": [], "trunk_group_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk Group object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Trunk Group object are included in the request body.

Delete Trunk Group

This request deletes a trunk group. All Trunks that have been created under the selected trunk group will be also deleted.

Method URL
DELETE /trunk_groups/{trunk_group_sid}

Path Arguments

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

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/trunk_groups/c7eae0b4-5eda-4964-8998-d514903b4af0' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.






Trunks

Trunks hold settings that will determine how the system will communicate with an endpoint. Trunks belong to trunk groups.

Trunk Object Reference

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

Attribute Data Type Description
trunk_sid string The trunk secure ID.
name string The trunk name.
endpoint_sid string The endpoint secure ID of the Endpoint associated with this trunk.
in_capacity integer The maximum number of simultaneous inbound calls. 0 means unlimited and is the default value.
out_capacity integer The maximum number of simultaneous outbound calls. 0 means unlimited and is the default value.
codec string The supported codec.
call_type integer The call type. Values accepted in this field are:
  • 0 for SIP only
  • 1 for with media. This is the default value.
  • 2 for 302 redirect
transformations object The transformations to apply to the trunk. Refer to the table below for more information.

transformations

Attribute Data Type Description
direction string The direction for the transformation. Values accepted in this field are inbound , outbound , and any .
action string The action to be executed for the transformation. Values accepted in this field are rewrite_to and rewrite_from .
operands array The values to be used for action .

Create Trunk

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

Method URL
POST /trunk_groups/{trunk_group_sid}/trunks

Path Arguments

Parameter Data Type Description
trunk_group_sid required string The secure of the Trunk Group that the Trunk will belong to.

Body Arguments

Data Type Description
object The body of the trunk to be created. Refer to the Trunk Object Reference for a list of fields that appear in the Trunk object. There are no required fields to create a Trunk object.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "trunk01", "endpoint_sid": null}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Get Trunks Matching the Specified Criteria

This request returns a list of trunks. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /trunk_groups/{trunk_group_sid}/trunks

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Get Trunk by SID

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

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

Path Arguments

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

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
404 Cannot find item by SID Ensure that the secure ID has been entered correctly.

Update Trunk

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

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

Path Arguments

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

Body Arguments

Data Type Description
object The fields and values of the trunk group to be updated. Refer to the Trunk Group Object Reference to see a list of fields that appear in the Trunk Group object. Fields that can be changed are:
  • call_type
  • codec
  • in_capacity
  • name
  • out_capacity
  • transformations

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-H 'Content-Type: application/json' \
--data-binary '{"name": "trunk_new_name", "endpoint_sid": null}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Trunk object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.



The PUT request below can be used to update an entire Trunk object. The trunk secure ID is passed in the query URL and the entire Trunk object is passed in the request body.

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

Path Arguments

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

Body Arguments

Data Type Description
object The entire Trunk Group object with any values to be updated. Refer to the Trunk Group Object Reference to see a list of fields that appear in the Trunk Group object. Fields that can be changed are:
  • call_type
  • codec
  • in_capacity
  • name
  • out_capacity
  • transformations

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/core/v2/trunk_groups/f3893c2c-90d2-46f5-917a-5dba613cab6d/trunks/21efab69-ded1-4c71-adbe-10584587189c' \
-H 'Content-Type: application/json' \
--data-binary '{"allow_forward": "disable", "call_type": "regular", "codec": null, "endpoint_sid": null, "in_capacity": 0, "name": "my_trunk", "out_capacity": 0, "relay_sip_headers": [], "transformations": [],  "trunk_sid": "aed1c137-8cbf-417c-8c41-e181f425826b"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "allow_forward": "disable",
    "call_type": "regular",
    "codec": null,
    "endpoint_sid": null,
    "in_capacity": 0,
    "name": "my_trunk",
    "out_capacity": 0,
    "relay_sip_headers": [],
    "transformations": [],
    "trunk_sid": "aed1c137-8cbf-417c-8c41-e181f425826b"
}

A successful request will return a 200 response code with a serialized copy of the Trunk object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all of the fields that appear in the Trunk object are included in the request body.

Delete Trunk

This request deletes a trunk, targeted by trunk and trunk group secure ID.

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

Path Arguments

Parameter Data Type Description
trunk_group_sid required string The secure ID of the trunk group to which the trunk belongs.
trunk_sid required string The secure ID of the trunk to be deleted.

Sample Curl Command

curl -X DELETE \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks/aed1c137-8cbf-417c-8c41-e181f425826b' \
-u '[your_user_name]:[your_password]'

A successful request will return a 204 response code with an empty body. Refer to the HTTP Status Codes section for a comprehensive list of errors.






Verification

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

Verification Email Object Reference

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

Attribute Data Type Description
status string The status of the verification. Possible values that appear in this field are: created , sent_email , and verified .
to_address string The verified email address.
base_url url The URL of the page to be re-addressed to after email verification.
email_template_sid string The email template secure ID.

Send Verification SMS

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

Method URL
POST /verification/sms

Path Arguments

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

Sample Curl Command

curl -X POST
'https://api.carrierx.com/core/v2/verification/sms?from_did=15162065574&to_did=18057224756&message=Your+verification+code+is+' \
-H "Content-Type: application/json"
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code. Below is a common error that arises when sending a verification SMS. Refer to the HTTP Status Codes section for more common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that all the values needed to send a verification SMS are included in the request. The required fields are from_did , and to_did .

Send Verification Email

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

Method URL
POST /verification/email

Body Arguments

Data Type Description
object The fields to apply to this request. Refer to the Verification Email Object Reference for a list of fields that appear in the Verification Email object. To send a verification email, to_address or partner_sid must be provided. If partner_sid is provided, the verification email will be sent to the owner_email of that partner.

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/verification/email' \
--data-binary '{"to_address": "jsmith@carrierx.com"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Verification Email object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.

Response Code Message Description
422 Object validation error Ensure that either a to_address or parttner_sid are included in the request.

Verify Email by Token

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

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

Body Arguments

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

Sample Curl Command

curl -X POST \
'https://api.carrierx.com/core/v2/verification/email/tokens/34ed4977-13c0-48bb-a509-1f35777e350b' \
-H 'Content-Type: application/json' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Verification Email object . Refer to the HTTP Status Codes section for common errors that may arise when making requests.


Email Template Object Reference

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

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

Get Email Templates Matching the Specified Criteria

This request returns the list of existing email templates. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /verification/email/templates

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/verification/email/templates?exclude_fields=html_body' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

This request returns a 200 response including an html_body field.

Get Email Template by SID

This request returns an Email Template object, targeted by the secure ID. This request is enabled for Field Filtering .

Method URL
GET /verification/email/templates/{template_sid}

Path Arguments

Parameter Data Type Description
template_sid required string The template secure ID.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/core/v2/verification/email/templates/465eb46b-05a7-4251-b89c-e99f2b81509b?exclude_fields=html_body' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
    "bcc_addresses": "jsmith@freeconferencecall.com",
    "cc_addresses": null,
    "from_address": "noreply@carrierx.com",
    "name": "Forgot Partner Password template",
    "subject": "QA: CarrierX Password Reset",
    "template_sid": "465eb46b-05a7-4251-b89c-e99f2b81509b",
    "text_body": "To complete your password reset, please click the link below:\n${base_url}?token=${uuid}\n\nYou are receiving this email because someone has initiated a password reset on\nyour account.\n\n4300 E. Pacific Coast Highway | Long Beach, CA | 90804\n",
    "to_addresses": null,
    "type": "forgot_partner_password"
}

This request returns a 200 response including an html_body field.

Response Code Message Description
404 Cannot find email template by SID Ensure that the secure ID has been entered correctly.





HTTP Status Codes

This section lists the HTTP status codes the API returns with each request. Note that additional error codes and messages are listed in the sections to which they pertain.


Success Response

Response Code Text Description
200 OK                               The request has succeeded. The information returned with the response depends on the method used in the request.

Error Responses

Response Code Text Description
400 Bad request The request could not be understood by the server due to incorrect syntax, improper formatting of a request, or invalid/unauthorized request. 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 Unauthorized The request requires user authentication.
401 Bad credentials The request requires correct 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.
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.
404 Not Found The requested resource was not found on the server.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.