Core API Reference Guide



Introduction

Welcome to the CarrierX RESTful API Reference Guide. This API Reference Guide will help you tap into the fundamental capabilities of the CarrierX platform through RESTful verbs to enable your application with Voice, Conference Calling, SMS and Verification services.

What's in this Reference Guide?

This API Reference Guide provides a simple and standardized RESTful interface with JSON formatted responses that can be used by developers to create connectivity between their applications and our communication infrastructure.

For immediate instruction, browse our Table of Contents to the left and jump to the specific section of interest.

There are four primary services that this API Reference Guide will allow you to provision.

These services are:

  • Phone Numbers: Customers can easily rent phone numbers through their CarrierX portal that are enabled with both audio and sms capabilities.
  • SMS Solutions: Utilizing either rented phone numbers or short codes, users can enable long code messaging and user verification workflows for their apps.
  • SIP Trunking: Quickly provision and support your application with high-quality audio with CarrierX SIP trunking.
  • Application Endpoints: Quickly provision robust, full-featured applications that can help deliver a voice-rich customer experience through redirecting, merging or hosting high-volume calls.

These four core capabilities work in concert to make up the breadth of capabilities available to customers with the CarrierX infrastructure. Through simple RESTful services we help you connect millions of callers daily and deliver international outbound services to more than 50 countries.

Enabling communication services at disruptive pricing has never been easier.

Getting Started

The CarrierX API can be accessed from the following base URL:


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

All data is sent and received in the JSON format and all of your API requests will require authentication. If you have not yet obtained your CarrierX account, please provide your email address on the homepage to create your free account.

If you prefer, you can contact our customer service team by phone to help you get started: (844) 844-1322.


Partners

Once you have obtained your CarrierX credentials, you are officially referred to as a Partner.

Having a Master Partner credential allows you to create additional sub-Partner accounts (or sub-accounts) each governed by its own set of Partner credentials. This multi-level hierarchical structure is an efficient method for managing your customers’ data and resources on an ad-hoc / stand-alone basis.

Get Partners Matching the Specified Criteria

Shows the list of Partners. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true, pagination field will suggest moving either to the next page or to the previous one. If you want to obtain data about a particular partner but cannot remember partner_sid, filter.
To see all sub-partner accounts for a particular partner, set filter to parent_sid eq 'partner_sid' and send the request.
Use the order and include_fields / exclude_fields parameters to adjust the response to your convenience.

Alongside with the items, the GET request will also return the following information:

  {
          "offset": 0,
          "limit": 10,
          "count": 10,
          "total": 541,
          "has_more": true,
          "pagination": {
              "next": "https://api.carrierx.com/core/v2/partners?limit=10&offset=10"
      }

Parameter Data Type Description
offset integer Amount of skipped items (as defined in the request)
limit integer Number of the returned items (as defined in the request)
count integer Number of items returned in the response.
count = limit – in case the ‘count’ value exceeds the defined ‘limit’
count < limit – in case number of the available items is less than defined ‘limit’
total integer Total amount of available items
has_more boolean Shows whether or not more items are available
pagination string The link leading to the next page if more items are available

METHOD URL
GET /partners

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners?limit=100&filter=name%20eq%20%22PQA_03%22%20and%20parent_sid%20ne%200'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq “PSTN-GW” and parent_sid ne 0
order string Specifies order of items in the response: asc, desc

Example:
name desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

  {
      "display_id": "CX49260055",
      "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
      "login": "fcc_login",
      "name": "Frederick K. Walker",
      "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f",
      "date_created": "2016-10-25T07:10:24.000Z",
      "balance": "-0.63",
      "owner_email": "aerialme0@yandex.ru",
      "billing_email": "aerialme0@yandex.ru",
      "tech_email": "oleni.lu4she@gmail.com",
      "company_name": "fcc77",
      "address1": "14802020698",
      "address2": null,
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85034",
      "country_code": "USA",
      "attributes": {},
      "payment_type": "postpay",
      "prepay_amount": null,
      "charge_at": null,
      "callbacks": {},
      "acls": [],
      "parent_assigned_acls": [],
      "transformations": [
          {
              "direction": "outbound",
              "action": "rewrite_to",
              "operands": [
                  "9999",
                  "18884521505"
                ]
          }
      ],
      "status": "active",
      "phonenumber": "180045012323"
  }

Attributes

Attribute Data Type Description
display_id string Partner unique ID
partner_sid opt string Partner secure ID
parent_sid opt string Parent Partner secure ID
name opt string Partner name
login string Login to the web or WS API
password string Password to the web or WS API. The field is hidden
date_created opt string Date and time when the partner was created
owner_email string Partner primary email,
billing_email string Partner email used for billing purposes; owner_email is used if empty
tech_email string Partner email used for technical purposes; owner_email is used if empty
company_name string Partner company name
status string Status of the partner. Possible values:
deleted – partner was removed
active –partner is active
canceled – partner was canceled
suspended – partner’s account has been suspended because his balance went lower the acceptable limit
unverified – partner’s email has not been verified
unconfirmed – partner has not been confirmed
phonenumber string Partner contact phone number
callbacks sms_callback_url opt string Callback URL for sms
acls opt acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule Secure IDs
parent_assigned_acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule Secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
balance opt integer Current balance of the Partner
address1 string Partner address
address2 string Partner address
city string Partner city
zip string Partner zip code
country_code string Partner country ISO 3166-1 alpha-3 code
prepay_amount integer Charge amount for prepay customers
charge_at integer Balance value when prepay account will be charged
payment_type string Type of payment. Posible values:
  • prepay
  • postpay

Create New Partner

This will add a new partner to the structure. The mandatory parameters are login, password, zip, country_code, owner_email. password value is seen only when sending the POST request and it is hidden in the response. If the full address is not specified at the creation step, it can be added later on with a PATCH call. Each partner is created with a unique login. If you try to add a partner with the “login” value already registered in the system, the call will return Response 400. Object validation error. parent_sid is specified, the secure ID of the Master account will be taken.

At the creation step, all partners can be determined as postpay or prepay:

  • Partners whth ‘payment_type’ set to ‘postpay’ are expected to pay for using CarrierX services at the end of each billing period (on a monthly basis)
  • Partners with ‘payment_type’ set to ‘prepay’ are expected to pay in advance using the services. The exceptable amount is defined in the prepay_amount attribute. The min possible value is ‘5’ (i.e. Partner can have at least 5 dollars on his account), and the max acceptable prepay amount is 1000. The charge_at parameter defines the lower margine. Once it is reached, the Partner will be charged for the same amount of money specified in the prepay_amount.

    Each Partner can control what calls can be placed or received with the help of Access Control Lists (ACL). Access Control List (ACL) consists of the list of List of Access Control Rules, i.e. single checks that determine the scope of data to be checked in SIP calls.

    ACL’s can exist both on the Partner and on the Trunk Group levels.
    On the Partner level, ACLs are defined in acls and parent_assigned_acls attributes.

    Note : acls can be set up only by the Partner himself.
    Note : parent_assigned_acls can be set up only by the Partner’s parent.

    ACL’s cannot be shared between Partner and his sub Partners, and have to be created specifically for each partner. If not done at the creation step, ACL’s can be added later with a PATCH or PUT calls.

    sms_action_true and sms_action_false define what action is to be executed for a particular ACL. Possible values are reject and accept.
    voice_action_true and voice_action_false define what action is to be executed for a particular ACL. Possible values are reject403, reject503, accept.

    Note : [sms/voice]_action_false or [sms/voice]_action_false is set to one of above values, the other one should be set to null. They cannot be set to some value simultaneously.
    For example: sms_action_true: “accept”, sms_action_false: null

    Email Management

    Each partner has 3 email addresses:

    • owner_email - Partner primary email;
    • billing_email - Partner email used for billing purposes; owner_email is used if empty
    • tech_email - Partner email used for technical purposes; owner_email is used if empty

     

    owner_email the only mandatory email address field which cannot be empty. It will remain Partner’s major contact  which will be used if his other email addresses

     

    Basic Workflow

    As soon as a new Partner is added to the system, we send a verification message to his email address (the one provided as owner_email).

    The email body will contain a link with a token, clicking which Partner will confirm his email address and his readiness to use CarrierX services. Until then, partner’s email address will not be shown as ‘owner_email’.

    If Partner skips the email confirmation step, his status in the system will remain unconfirmed, i.e. he won't be able to use any of the CarrierX services.

    Once the address is confirmed, the email value will show up in owner_email field and will be used as Partner's primary contact address.

    The same workflow applies to the other 2 email addresses (billing_email and tech_email addresses):

    Important: if the tech_email and/or billing_email coincide with the owner_email value, no new confirmation email is sent, and the email values are set up automatically.

    However, if the tech_email and/or billing_email do NOT coincide with the owner_email value, the confirmation email is sent to each newly specified email

    METHOD URL
    POST /partners

    Sample URL

    
curl -X POST --header 'Content-Type: application/json' -d '{"login":"fcc_login", "password":"fcc_password", "name":"Mary C. Burge", "company_name": "ABC", "parent_sid":"", "country_code":"USA", "zip":"92701", "owner_email": "MaryCBurge@teleworm.us", "payment_type": "postpay", "phonenumber": "180045012323"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners'

    Parameters

    Parameter Data Type Description
    body req ... Body of the Partner to be created.

    Sample Response

      {
      "display_id": "CX49260055",
      "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
      "login": "fcc_login ",
      "name": "Mary C. Burge ",
      "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f",
      "date_created": "2016-10-25T07:10:24.000Z",
      "balance": "5",
      "owner_email": "MaryCBurge@teleworm.us",
      "billing_email": "MaryCBurge@teleworm.us",
      "tech_email": "MaryCBurge@teleworm.us",
      "company_name": "ABC ",
      "address1": "Colebrook way 17",
      "address2": null,
      "city": "",
      "state": "",
      "zip": "92701",
      "country_code": "USA",
      "attributes": {},
      "payment_type": "postpay",
      "prepay_amount": null,
      "charge_at": null,
      "callbacks": {},
      "acls": [],
      "parent_assigned_acls": [],
      "transformations": [],
      "status": "active",
      "phonenumber": "180045012323"
  }

    Attributes

    Attribute Data Type Description
    display_id string Partner unique ID
    partner_sid opt string Partner secure ID
    parent_sid opt string Parent Partner secure ID
    name opt string Partner name
    login string Login to the web or WS API
    password string Password to the web or WS API. The field is hidden
    date_created opt string Date and time when the partner was created
    owner_email string Partner primary email,
    billing_email string Partner email used for billing purposes; owner_email is used if empty
    tech_email string Partner email used for technical purposes; owner_email is used if empty
    company_name string Partner company name
    status string Status of the partner. Possible values:
    deleted – partner was removed
    active –partner is active
    canceled – partner was canceled
    suspended – partner’s account has been suspended because his balance went lower the acceptable limit
    unverified – partner’s email has not been verified
    unconfirmed – partner has not been confirmed
    phonenumber string Partner contact phone number
    callbacks sms_callback_url opt string Callback URL for sms
    acls opt acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    parent_assigned_acls acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    transformations direction string Direction for transformation:
    inbound, outbound, any
    action string Action to be executed for transformation:
    rewrite_to, rewrite_from
    operands array Value(s) to be used for "action"
    balance opt integer Current balance of the Partner
    address1 string Partner address
    address2 string Partner address
    city string Partner city
    zip string Partner zip code
    country_code string Partner country ISO 3166-1 alpha-3 code
    prepay_amount integer Charge amount for prepay customers
    charge_at integer Balance value when prepay account will be charged
    payment_type string Type of payment. Posible values:
    • prepay
    • postpay

    Remove Partner

    This call will remove one of your Partners from the structure. This action is not possible to accomplish until the selected Partner owns sub-partners. Ensure you delete the total sub-partner accounts structure prior to removing the parent one.

    METHOD URL
    DELETE /partners/{partner_sid}

    Sample URL

    
curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/ILaI971X9-cKufSR.DrUFgqGbufXomDq'

    Parameters

    Parameter Data Type Description
    partner_sid req string Secure ID of the Partner to be removed

    Get Partner by SID

    This call will return information for a single Partner whose secure ID is used to retrieve the data. You may use include_fields / exclude_fields parameters to refine the response.

    METHOD URL
    GET /partners/{partner_sid}

    Sample URL

    
curl -X GET --header 'Content-Type: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/6feb0f8b-f104-4445-8db8-593c5e5cb7ee'

    Parameters

    Parameter Data Type Description
    partner_sid req string Partner secure ID
    include_fields string Comma separated list of fields that should be included in the response
    exclude_fields string Comma separated list of fields that should be excluded from the response

    Sample Response

     {
          "display_id": "CX49260055",
          "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
          "login": "fcctest_anovikova",
          "name": "Frederick K. Walker",
          "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f",
          "date_created": "2016-10-25T07:10:24.000Z",
          "balance": "-0.63",
          "owner_email": "aerialme0@yandex.ru",
          "billing_email": "aerialme0@yandex.ru",
          "tech_email": "oleni.lu4she@gmail.com",
          "company_name": "fcc77",
          "address1": "14802020698",
          "address2": null,
          "city": "Phoenix",
          "state": "AZ",
          "zip": "85034",
          "country_code": "USA",
          "attributes": {},
          "payment_type": "postpay",
          "prepay_amount": null,
          "charge_at": null,
          "callbacks": {},
          "acls": [],
          "parent_assigned_acls": [],
          "transformations": [
              {
                  "direction": "outbound",
                  "action": "rewrite_to",
                  "operands": [
                      "9999",
                      "18884521505"
                  ]
              }
          ],
          "status": "active",
          "phonenumber": "180045012323"
  }

    Attributes

    Attribute Data Type Description
    display_id string Partner unique ID
    partner_sid opt string Partner secure ID
    parent_sid opt string Parent Partner secure ID
    name opt string Partner name
    login string Login to the web or WS API
    password string Password to the web or WS API. The field is hidden
    date_created opt string Date and time when the partner was created
    owner_email string Partner primary email,
    billing_email string Partner email used for billing purposes; owner_email is used if empty
    tech_email string Partner email used for technical purposes; owner_email is used if empty
    company_name string Partner company name
    status string Status of the partner. Possible values:
    deleted – partner was removed
    active –partner is active
    canceled – partner was canceled
    suspended – partner’s account has been suspended because his balance went lower the acceptable limit
    unverified – partner’s email has not been verified
    unconfirmed – partner has not been confirmed
    phonenumber string Partner contact phone number
    callbacks sms_callback_url opt string Callback URL for sms
    acls opt acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    parent_assigned_acls acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    transformations direction string Direction for transformation:
    inbound, outbound, any
    action string Action to be executed for transformation:
    rewrite_to, rewrite_from
    operands array Value(s) to be used for "action"
    balance opt integer Current balance of the Partner
    address1 string Partner address
    address2 string Partner address
    city string Partner city
    zip string Partner zip code
    country_code string Partner country ISO 3166-1 alpha-3 code
    prepay_amount integer Charge amount for prepay customers
    charge_at integer Balance value when prepay account will be charged
    payment_type string Type of payment. Posible values:
    • prepay
    • postpay

    Patch Partner

    This call performs a partial update of the Partner. You may use it to change partner’s password, update address, to add or remove objects like acls, transformations.
    Note: only parameters specified in the call will be updated. The other will preserce their current value. Arrays of complex objects (like alcs, transformations) get totally replaced by the new values. If a PATCH call contains an acl or transformation object, it will totally replace the existing one if any. In order to add a new transformation or acl, send the request containing both the existing object(s) and the one to be added.
    Note: acls can be set up or updated only by the Partner himself.
    Note: parent_assigned_acls can be set up or updated only by the Partner’s parent.

    sms_action_true and sms_action_false define what action is to be executed for a particular ACL. Possible values are reject and accept.

    Note: If either [sms/voice]_action_true or [sms/voice]_action_false is set to one of above values, the other one should be set to null. They cannot be set to some value simultaneously.

    For example: voice_action_true: "accept", voice_action_false: null.

    METHOD URL
    PATCH /partners/{partner_sid}

    Sample URL

    
curl -X PATCH --header 'Content-Type: application/json' –d '{"password":"oc25"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/6feb0f8b-f104-4445-8db8-593c5e5cb7ee'

    Parameters

    Parameter Data Type Description
    partner_sid req string Partner secure ID
    body req ... Body of the Partner to be patched


    Sample Response

     {
          "display_id": "CX49260055",
          "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
          "login": "fcctest_anovikova",
          "name": "Frederick K. Walker",
          "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f",
          "date_created": "2016-10-25T07:10:24.000Z",
          "balance": "-0.63",
          "owner_email": "aerialme0@yandex.ru",
          "billing_email": "aerialme0@yandex.ru",
          "tech_email": "oleni.lu4she@gmail.com",
          "company_name": "fcc77",
          "address1": "14802020698",
          "address2": null,
          "city": "Phoenix",
          "state": "AZ",
          "zip": "85034",
          "country_code": "USA",
          "attributes": {},
          "payment_type": "postpay",
          "prepay_amount": null,
          "charge_at": null,
          "callbacks": {},
          "acls": [],
          "parent_assigned_acls": [],
          "transformations": [
              {
                  "direction": "outbound",
                  "action": "rewrite_to",
                  "operands": [
                      "9999",
                      "18884521505"
                  ]
              }
          ],
          "status": "active",
          "phonenumber": "180045012323"
  }

    Attributes

    Attribute Data Type Description
    display_id string Partner unique ID
    partner_sid opt string Partner secure ID
    parent_sid opt string Parent Partner secure ID
    name opt string Partner name
    login string Login to the web or WS API
    password string Password to the web or WS API. The field is hidden
    date_created opt string Date and time when the partner was created
    owner_email string Partner primary email,
    billing_email string Partner email used for billing purposes; owner_email is used if empty
    tech_email string Partner email used for technical purposes; owner_email is used if empty
    company_name string Partner company name
    status string Status of the partner. Possible values:
    deleted – partner was removed
    active –partner is active
    canceled – partner was canceled
    suspended – partner’s account has been suspended because his balance went lower the acceptable limit
    unverified – partner’s email has not been verified
    unconfirmed – partner has not been confirmed
    phonenumber string Partner contact phone number
    callbacks sms_callback_url opt string Callback URL for sms
    acls opt acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    parent_assigned_acls acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    transformations direction string Direction for transformation:
    inbound, outbound, any
    action string Action to be executed for transformation:
    rewrite_to, rewrite_from
    operands array Value(s) to be used for "action"
    balance opt integer Current balance of the Partner
    address1 string Partner address
    address2 string Partner address
    city string Partner city
    zip string Partner zip code
    country_code string Partner country ISO 3166-1 alpha-3 code
    prepay_amount integer Charge amount for prepay customers
    charge_at integer Balance value when prepay account will be charged
    payment_type string Type of payment. Posible values:
    • prepay
    • postpay

    Update Partner

    This call performs a complete update of the Partner. This call can be used both for changing and removing values. The mandatory attributes: login, country_code, zip cannot be null.
    Note: acls can be set up or updated only by the Partner himself.
    Note: parent_assigned_acls can be set up or updated only by the Partner’s parent.

    sms_action_true and sms_action_false define what action is to be executed for a particular ACL. Possible values are reject and accept.
    voice_action_true and voice_action_false define what action is to be executed for a particular ACL. Possible values are reject503, reject403, accept.
    Note: If either sms/voice_action_true or sms/voice_action_false is set to one of above values, the other one should be set to null. They cannot be set to some value simultaneously.
    For example: "voice_action_true":"accept", "voice_action_false":null.

    METHOD URL
    PUT /partners/{partner_sid}

    Sample URL

    
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' –d  '{"display_id": "CX49260055", "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee", "login": "fcctest_anovikova", "name": "Frederick K. Walker", "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f", "date_created": "2016-10-25T07:10:24.000Z", "balance": "-0.63", "owner_email": "aerialme0@yandex.ru", "billing_email": "aerialme0@yandex.ru", "tech_email": "oleni.lu4she@gmail.com", "company_name": "fcc77", "address1": "14802020698", "address2": null, "city": "Phoenix", "state": "AZ", "zip": "85034", "country_code": "USA", "attributes": {}, "payment_type": "postpay", "prepay_amount": null, "charge_at": null, "callbacks": {}, "acls": [], "parent_assigned_acls": [], "transformations": [ { "direction": "outbound", "action": "rewrite_to", "operands": [ "9999", "18884521505" ] } ], "status": "active", "phonenumber": "180045012323" }' -u [your_user_name]:[your_password]'https://api.carrierx.com/core/v2/partners/6feb0f8b-f104-4445-8db8-593c5e5cb7ee'

    Parameters

    Parameter Data Type Description
    partner_sid req string Partner secure ID
    body req ... Body of the Partner to be updated

    Sample Response

     {
    "display_id": "CX49260055",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "login": "fcctest_anovikova",
    "name": "Frederick K. Walker",
    "parent_sid": "lbVk92xwB-eKLZKlahZkPR9O7JBp8Y-f",
    "date_created": "2016-10-25T07:10:24.000Z",
    "balance": "-0.63",
    "owner_email": "aerialme0@yandex.ru",
    "billing_email": "aerialme0@yandex.ru",
    "tech_email": "oleni.lu4she@gmail.com",
    "company_name": "fcc77",
    "address1": "14802020698",
    "address2": null,
    "city": "Phoenix",
    "state": "AZ",
    "zip": "85034",
    "country_code": "USA",
    "attributes": {},
    "payment_type": "postpay",
    "prepay_amount": null,
    "charge_at": null,
    "callbacks": {},
    "acls": [],
    "parent_assigned_acls": [],
    "transformations": [
        {
            "direction": "outbound",
            "action": "rewrite_to",
            "operands": [
                "9999",
                "18884521505"
            ]
        }
    ],
    "status": "active",
    "phonenumber": "180045012323"
}

    Attributes

    Attribute Data Type Description
    display_id string Partner unique ID
    partner_sid opt string Partner secure ID
    parent_sid opt string Parent Partner secure ID
    name opt string Partner name
    login string Login to the web or WS API
    password string Password to the web or WS API. The field is hidden
    date_created opt string Date and time when the partner was created
    owner_email string Partner primary email,
    billing_email string Partner email used for billing purposes; owner_email is used if empty
    tech_email string Partner email used for technical purposes; owner_email is used if empty
    company_name string Partner company name
    status string Status of the partner. Possible values:
    deleted – partner was removed
    active –partner is active
    canceled – partner was canceled
    suspended – partner’s account has been suspended because his balance went lower the acceptable limit
    unverified – partner’s email has not been verified
    unconfirmed – partner has not been confirmed
    phonenumber string Partner contact phone number
    callbacks sms_callback_url opt string Callback URL for sms
    acls opt acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    parent_assigned_acls acl direction string Direction for ACL. Possible values:
    inbound, outbound, any
    voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
    accept, reject403, reject503
    sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
    accept, reject
    sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
    accept, reject
    access_control_rules array List of Access Control Rule Secure IDs
    transformations direction string Direction for transformation:
    inbound, outbound, any
    action string Action to be executed for transformation:
    rewrite_to, rewrite_from
    operands array Value(s) to be used for "action"
    balance opt integer Current balance of the Partner
    address1 string Partner address
    address2 string Partner address
    city string Partner city
    zip string Partner zip code
    country_code string Partner country ISO 3166-1 alpha-3 code
    prepay_amount integer Charge amount for prepay customers
    charge_at integer Balance value when prepay account will be charged
    payment_type string Type of payment. Posible values:
    • prepay
    • postpay


Billing Methods

The call will register the billing method for a particular customer. The mandatory fields are type, cc_number, name, cc_expiration, zip, country_code, phonenumber if applicable. When registering a credit card, the credit card number is shown only in the request, and is not fully returned as plain text in the response. Ensure the provided zip code is the existing one. The system will return error otherwise.

Register Billing Method

The call will register the billing method for a particular customer. The mandatory fields are type, cc_number, name, cc_expiration, zip, country_code, phonenumber.

METHOD URL
POST /partners/{partner_sid}/billing_method

Sample URL


curl -X GET --header 'Accept: application/json' -d '{"type":"visa", "cc_number":"4444444444445555", "cc_expiration":"092016", "cc_cid":"5569", "ec_account_number":"01564789987654", "name":"HG455", "address1":"90207 USA", "address2":"Colebrook Way bld 16", "city":"Stockton", "state":"CA", "zip":"90270", "country_code":"USA", "phone":"18004501575" }' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/3b2e9fe7-e22e-4f03-8886-b5a84f851a6a/billing_method'

Parameters

Parameter Data Type Description
partner_sid req string Partner secure ID
body req ... Body of the billing method to be registered

Sample Response

 {
  "type": "visa",
  "cc_number": "4444",
  "cc_expiration": "092016",
  "name": "HG445",
  "address1": "90207 USA",
  "address2": "Colebrook Way bld 16",
  "city": "Stockton",
  "state": "CA",
  "zip": "90270",
  "country_code": "USA",
  "phone": "18004501575"
}

Attributes

Attribute Data Type Description
type string Type of the billing method:
  • american_express
  • visa
  • master_card
  • discover_card
  • diners_club
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number opt string Credit card number
cc_expiration opt string Credit card expiration date in 'mmyyyy' format
cc_cid string Credit card CID
ec_account_number opt string Electronic check account number
ec_routing_number opt string Electronic check routing number
name opt string Customer name
address1 opt string Customer address
address2 opt string Customer address
city opt string Customer city
state opt string Customer state: two-letter abbreviation code
zip opt string Customer zip code
country_code opt string Customer country in ISO 3166-1 alpha-3 code
phone opt string Customer phone number

Get Billing Method Information by Partner SID

The call will return information registered for the selected partner.

METHOD URL
GET /partners/{partner_sid}/billing_method

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/3b2e9fe7-e22e-4f03-8886-b5a84f851a6a/billing_method'

Parameters

Parameter Data Type Description
partner_sid req string Partner secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "type": "visa",
  "cc_number": "4444",
  "cc_expiration": "092016",
  "name": "HG445",
  "address1": "90207 USA",
  "address2": "Colebrook Way bld 16",
  "city": "Stockton",
  "state": "CA",
  "zip": "90270",
  "country_code": "USA",
  "phone": "18004501575"
}

Attributes

Attribute Data Type Description
type string Type of the billing method:
  • american_express
  • visa
  • master_card
  • discover_card
  • diners_club
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number opt string Credit card number
cc_expiration opt string Credit card expiration date in 'mmyyyy' format
cc_cid string Credit card CID
ec_account_number opt string Electronic check account number
ec_routing_number opt string Electronic check routing number
name opt string Customer name
address1 opt string Customer address
address2 opt string Customer address
city opt string Customer city
state opt string Customer state: two-letter abbreviation code
zip opt string Customer zip code
country_code opt string Customer country in ISO 3166-1 alpha-3 code
phone opt string Customer phone number

Remove Billing Method

This call will remove billing method of the partner whose secure ID is specified. When completed, no billing method will be registered for the specified partner.

METHOD URL
DELETE /partners/{partner_sid}/billing_method

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/partners/a771afc7-8856-4bd7-b24d-1cc3bcd1273c/billing_method'

Parameters

Parameter Data Type Description
partner_sid req string Secure ID of the Partner whose billing method is to be removed



OAuth

You can use either your master account credentials to access API, or any of your partner’s (i. e. sub accounts). Each partner has access to his and only his resources. To be able to access resources of another partner, use his partner_sid and access_token.

Revoke Current OAuth Token

This call will terminate your session.

METHOD URL
POST /oauth/logout

Sample URL


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



Revoke OAuth Token

This will terminate session of the partner whose token is specified.

METHOD URL
POST /oauth/revoke/{token}

Sample URL


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

Parameters

Parameter Data Type Description
token req string Access token


Get OAuth Bearer Token

This call generates the token for a partner upon request.

METHOD URL
POST /oauth/token

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -u [your_user_name]:[your_password] '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'

Parameters

Parameter Data Type Description
grant_type req string Grant type for this token
client_id req string Client ID, unique string representing the registration information provided to the client upon request (see also rfc6749)
client_secret req string Client secret, unique string representing the registration information provided to the client upon request (see also rfc6749)
username req string Login of the partner
password req string Password of the partner
scope req string Scope of the access request available for the client

Sample Response

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

Attributes

Attribute Data Type Description
access_token string Access token string
token_type string Type of the token
refresh_token string Refresh token
expires_in string Number of seconds during which the token will be valid
scope string Scope of the access request available for the client


Get All Active OAuth Bearer Tokens for the Partner

Shows tokens for the logged in partner that haven’t yet been expired.

METHOD URL
GET /oauth/token

Sample URL


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

Sample Response

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

Attributes

Attribute Data Type Description
access_token string Access token string
token_type string Type of the token
refresh_token string Refresh token
expires_in string Number of seconds during which the token will be valid
scope string Scope of the access request available for the client

Get the Currently Logged in Partner

The call will return the currently logged in partner.

METHOD URL
GET /oauth/whoami

Sample URL


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

Sample Response

 {
"name": "ROOT",
"login": "carrierx",
"partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
"parent_sid": null
}

Attributes

Attribute Data Type Description
name string Partner secure ID
parent_sid opt string Parent Partner secure ID
name opt string Partner name
login string Login to the web or WS API
password string Password to the web or WS API. The field is hidden





Endpoints

Next step after partner creation will be creating and assigning endpoints. If a partner is not specified at the creation step, the new endpoint will be automatically assigned to the currently logged in parent partner.

Depending on your needs and purposes, you may create endpoints for direct (one-stage) and indirect (two-stage) dialing.
For one-stage dialing, callers dial the direct number of the destination point (type=third_party, conference).
For two-stage dialing, callers dial the redirect CarrierX number which further puts the call through to the desired destination number (type=mediator).
Whenever a new partner is added to the system, the CarrierX provides it with the CarrierX IVS Endpoint. None of its attributes can be modified. (type=system_gateway)

Get Endpoints Matching the Specified Criteria

Shows the list of existing Endpoints. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true, pagination field will suggest moving either to the next page or the previous one.
You may obtain the list of endpoints of a particular type by setting the filter for type value.

Alongside with the items, the GET request will also return the following information:

{
  "offset": 0,
  "limit": 10,
  "count": 10,
  "total": 541,
  "has_more": true,
  "pagination": {
      "next": "https://api.carrierx.com/core/v2/endpoints?limit=10&offset=10"
  },

Parameter Data Type Description
offset integer Amount of skipped items (as defined in the request)
limit integer Number of the returned items (as defined in the request)
count integer Number of items returned in the response.
count = limit – in case the ‘count’ value exceeds the defined ‘limit’
count < limit – in case number of the available items is less than defined ‘limit’
total integer Total amount of available items
has_more boolean Shows whether or not more items are available
pagination string The link leading to the next page if more items are available

METHOD URL
GET /endpoints

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints?filter=capacity%20ne%200&order=type'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq Test
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response (type = third_party)

 {
    "endpoint_sid": "9fbfee56-5ded-4e65-a22c-697cd0331c16",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "name": "Endpoint_name",
    "type": "third_party",
    "voip_token": null,
    "capacity": 0,
    "addresses": [
        {
            "ip": "162.251.181.136",
            "port": 5060,
            "direction": "any",
            "transport": "udp"
        },
        {
            "ip": "162.251.183.11",
            "port": 5060,
            "direction": "any",
            "transport": "udp"
        },
        {
            "ip": "12.7.192.27",
            "port": 5060,
            "direction": "any",
            "transport": "udp"
        }
    ],
    "attributes": {},
    "transformations": []
}

Sample Response (type = system_gateway)

 {
   {
          "endpoint_sid": "ad4e17aa-6ced-4925-8fd1-a3824bbfabf2",
          "partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
          "name": "N/A",
          "type": "system_gateway",
          "voip_token": null,
          "capacity": 0,
          "addresses": [
              {
                  "ip": "2.2.22.2",
                  "port": 5060,
                  "transport": "udp"
              }
          ],
          "attributes": {},
          "transformations": []
      }

Sample Response (type = mediator)

 {
  "endpoint_sid": "ded7064b-8240-457b-b167-081b1d8088ff",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "2stage",
  "type": "mediator",
  "voip_token": "82de7c48-6e26-48c4-b3d1-891978e51802",
  "capacity": 0,
  "addresses": [
    {
      "ip": "12.7.192.202",
      "port": 5060,
      "transport": "udp"
    },
    {
      "ip": "12.7.192.203",
      "port": 5060,
      "transport": "udp"
    }
  ],
  "attributes": {
    "api_url": 'https://api.carrierx.com/mediator/v1/",
    "login": "VVP_01_mediator_159",
    "password": "BILiiZVBg3Qv",
    "account_sid": "088d9d0f-5fba-43df-82e2-92709596c9d0"
  }
  "transformations": [
    {
      "direction": "outbound",
      "action": "rewrite_from",
      "operands": [
          "14564423",
          "22224567"
      ]
    }
  ]
}

Sample Response (type = conference)

 {
  "endpoint_sid": "976b48e4-8ef1-4c08-94e2-d0c42a06c15a",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "conference",
  "type": "conference",
  "voip_token": "cce86a5e-a506-471c-b833-1179167958b4",
  "capacity": 0,
  "addresses": [
      {
          "ip": "10.2.111.72",
          "port": 5060,
          "transport": "udp"
      }
  ],
  "attributes": {
      "api_url": 'https://api.carrierx.com/conference/v1",
      "did_group_id": "106",
      "login": "VVP_01_conference_207",
      "subscriber_sid": "N7HM94Wi5-dLHfTukcZBJqUpl7Off1X1",
      "password": "nkLs7ODSOvnF"
  },
  "transformations": [
      {
          "direction": "outbound",
          "action": "rewrite_to",
          "operands": [
              "4242",
              "180045651222"
          ]
      }
  ]
}

Sample Response (type = flexml)

 {
  "endpoint_sid": "b8c38808-d0ce-4a88-99ef-39b74a79ed9c",
  "partner_sid": "1dd7c274-210d-414a-911d-e6b920e06d63",
  "name": "jan17_pv",
  "type": "flexml",
  "voip_token": "38ba4bfe-b3f2-4031-bce4-01f0ee991595",
  "capacity": 0,
  "addresses": [
       {
          "ip": "10.222.2.197",
          "port": 5060,
          "transport": "udp"
       }
   ],
   "attributes": {
          "api_url": 'https://api.carrierx.com/flexml/v1",
          "login": "jan17_prog_voice_498",
          "password": "jV6zwrB0kZ5J",
          "account_sid": "9b33245f-27c2-48e6-bf7f-25af725a0eda"
    },
   "transformations": []
}

Note: If you search for a particular endpoint, you may narrow down your search by filtering items by any of the inner fields (for example, IP address):

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints?offset=0&limit=10&filter=addresses.ip%20eq%20%22162.251.181.136%22'

Sample Response

{
  "endpoint_sid": "9fbfee56-5ded-4e65-a22c-697cd0331c16",
  "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
  "name": "Core Endpoint",
  "type": "system_gateway",
  "voip_token": null,
  "capacity": 0,
  "addresses": [
      {
          "ip": "162.251.181.136",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      }
  ],
  "attributes": {},
  "transformations": []
}

Attributes

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
voip_token opt string Endpoint authentication token
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
addresses ip string IP address
port opt integer Port. Default value is 5060
direction string Direction for this address = ['inbound', 'outbound', 'any (default)']
transport string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes key string Attribute key
value string Attribute value
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Create New Endpoint

This call creates a new endpoint. The mandatory fields are ip and type. port if not defined will be set to default value 5060. name if not provided will be set to N/A and can be modified later on with PATCH call.


NOTE: Setting the type value to mediator will create a Mediator Endpoint. This is a hosted Endpoint that CarrierX provides to a partner. Unlike endpoints of type = third_party, mediator endpoint configuration cannot be modified with PATCH or UPDATE calls. Values for name and capacity attributes are editable only.

NOTE: Setting type value to conference will create a Conference Endpoint. This is a hosted Endpoint that CarrierX can provide to a partner. The conference endpoint cannot be modified with PATCH or UPDATE calls. Values for name and capacity attributes are editable only.

NOTE: Setting flexml will create a FlexML Endpoint. This is a hosted Endpoint that CarrierX can provide to a partner. The FlexML endpoint configuration cannot be modified with PATCH or UPDATE calls. Values for name and capacity attributes are editable only.

NOTE: Carrier IVS Endpoints can be neither set up nor removed.

METHOD URL
POST /endpoints

Sample URL for third party endpoint (type = third_party)


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name":"EP_Т_1","addresses": ["ip": "1.1.2.13", "port": "5060"}], "type":"third_party"}’ -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints'

Sample URL for Mediator endpoint (type = mediator)


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name":"2stage", "type":"mediator"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints'

Sample URL for Conference endpoint (type = conference)


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name":"wyde_conf_EP", "type":"conference"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints'

Sample URL for FlexML endpoint (type = flexml)


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name":"flexml", "type":"flexml"}' -u [your_user_name]:[your_password] https://api.carrierx.com/core/v2/endpoints


Parameters

Parameter Data Type Description
body req ... Body of the Endpoint to be created

Sample Response for type = third_party

 {
  "endpoint_sid": "dc0b2da4-8679-484b-b7c3-7d7a4d11df15",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "EP_Т_1",
  "type": "third_party",
  "voip_token": "d02f37bf-286f-46e0-ad7e-22260e46a405",
  "capacity": 0,
  "addresses": [
      {
          "ip": "1.1.2.13",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      }
  ],
  "attributes": {},
  "transformations": []
}

Sample Response (type = mediator)

 {
  "endpoint_sid": "ded7064b-8240-457b-b167-081b1d8088ff",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "2stage",
  "type": "mediator",
  "voip_token": "82de7c48-6e26-48c4-b3d1-891978e51802",
  "capacity": 0,
  "addresses": [
      {
          "ip": "12.7.192.202",
          "port": 5060,
          "transport": "udp"
      },
      {
          "ip": "12.7.192.203",
          "port": 5060,
          "transport": "udp"
      }
  ],
  "attributes": {
      "api_url": 'https://api.carrierx.com/mediator/v1",
      "login": "VVP_01_mediator_159",
      "password": "BILiiZVBg3Qv",
      "account_sid": "088d9d0f-5fba-43df-82e2-92709596c9d0"
  },
  "transformations": []
}

Sample Response (type = conference)

 {
  "endpoint_sid": "c32dd688-beaa-4a2f-817f-e30cb7152ffa",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "wyde_conf_EP",
  "type": "conference",
  "voip_token": "2cc5b4cb-bde1-4a09-9a5e-82d8d70aa593",
  "capacity": 0,
  "addresses": [
      {
          "ip": "10.2.111.72",
          "port": 5060,
          "transport": "udp"
      }
  ],
  "attributes": {
      "did_group_id": "110",
      "api_url": 'https://api.carrierx.com/conference/v1",
      "subscriber_sid": "hPIj91cXDvdMxLLsmWglp5a4iB6yW-k1",
      "login": "VVP_01_conference_870",
      "password": "i9YNsm3bp5Do"
  },
  "transformations": []
}

Sample Response (type = flexml)

{
  "endpoint_sid": "b0e5260b-b256-4263-9baa-fd9b81237257",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "name": "flexml",
  "type": "flexml",
  "voip_token": "9f0f25a1-97b4-4da3-a475-e6c1d21610c2",
  "capacity": 0,
  "addresses": [
      {
          "ip": "10.222.2.197",
          "port": 5060,
          "transport": "udp"
      }
  ],
  "attributes": {
      "api_url": 'https://api.carrierx.com/flexml/v1",
      "login": "carrierx_test_flexml_551",
      "password": "8R5o33nPS1Li",
      "account_sid": "9c7dfcba-f3c7-483e-b4fa-eea40cc1bce3"
  },
  "transformations": []
}

Attributes

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
voip_token opt string Endpoint authentication token
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
addresses ip string IP address
port opt integer Port. Default value is 5060
direction string Direction for this address = ['inbound', 'outbound', 'any (default)']
transport string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes key string Attribute key
value string Attribute value
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"


Attributes For Two Stage Endpoint (type = mediator)

,
Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
voip_token opt string Endpoint authentication token
addresses ip string IP address. Cannot be modified. Cannot be modified.
port opt integer Port. Default value is 5060. Cannot be modified.
transport opt string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes api_url string URL to Mediator swagger. Cannot be modified.
login string Login to access Mediator API. Cannot be modified.
password string Password to access Mediator API. Cannot be modified.
account_sid string Secure ID of the Mediator account. Cannot be modified.
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Attributes For Conference (type = conference)

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
voip_token opt string Endpoint authentication token
addresses tag string Address tag for the Trunk. Cannot be modified.
ip string IP address. Cannot be modified. Cannot be modified.
port opt integer Port. Default value is 5060. Cannot be modified.
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes api_url string URL to Conference API
did_group_id integer DID group ID in Conference API
login string Login to access Conference
password string Password to access Conference
subscriber_sid string Conference subscriber secure ID
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Attributes For FlexML (type = flexml)

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
voip_token opt string Endpoint authentication token
addresses tag string Address tag for the Trunk. Cannot be modified.
ip string IP address. Cannot be modified. Cannot be modified.
port opt integer Port. Default value is 5060. Cannot be modified.
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes api_url string URL to Conference API
did_group_id integer DID group ID in Conference API
login string Login to access Conference
password string Password to access Conference
subscriber_sid string Conference subscriber secure ID
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Remove Endpoint

This call removes an Endpoint from the Partner account.

CarrierX IVS Endpoints can be neither created nor removed.

METHOD URL
DELETE /endpoints/{endpoint_sid}

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints/J0x698QJYfd9UNlAZ8Qkl0U4Pf6xazvv'

Parameters

Parameter Data Type Description
endpoint_sid req string Secure ID of the Endpoint to be removed.

Get Endpoint by SID

This call retrieves an Endpoint which secure ID is specified. You may refine the reponse with include_fields / exclude_fields parameters.

METHOD URL
GET /endpoints/{endpoint_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a'

Parameters

Parameter Data Type Description
endpoint_sid req string Endpoint secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
  "endpoint_sid": "00bf8b25-1e20-4f80-8529-8448df32d71a",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "3rdParty",
  "type": "third_party",
  "voip_token": "ab72ad7a-568b-466e-9fd9-407de0313e36",
  "capacity": 0,
  "addresses": [
      {
          "ip": "1.1.2.2",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      },
      {
          "ip": "2.2.2.3",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      }
  ],
  "attributes": {},
  "transformations": []
}

Attributes

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
voip_token opt string Endpoint authentication token
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
addresses ip string IP address
port opt integer Port. Default value is 5060
direction string Direction for this address = ['inbound', 'outbound', 'any (default)']
transport string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes key string Attribute key
value string Attribute value
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
accept, reject
action string Action to be executed for transformation:
accept, reject
operands array Value(s) to be used for "action"

Patch Endpoint

This call performs partial update of the Endpoint and is well suitable for updating single parameters.

Note: only parameters specified in the call will be updated. The rest will preserve their current values.

Arrays of complex objects (like addresses, transformations) get totally replaced by the new values. If a PATCH call contains an address or transformation object, it will totally replace the existing one if any. In order to add a new address or transformation, send the request containing both the existing object(s) and the one to be added.

The attributes parameter is defined as a set of key-value pairs: "key": "value" The PATCH call will do one of the following:

  • add new set of "key": “value” pair if the key is new;
  • replace the "value" if the key already exisits for this endpoint;
  • remove the key-value pair, if the existing key and the new value = null.

Note: For Mediator (type = mediator) and Conference Endpoints (type = conference), only name and capacity fields are editable. Any attempt to modify addresses or attributes fields will return Response 400. Object validation error.

METHOD URL
PATCH /endpoints/{endpoint_sid}

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"addresses": [{"ip": "15.1.12.6", "port": "5060"}]}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a'

Parameters

Parameter Data Type Description
endpoint_sid req string Endpoint secure ID
body req ... Body of the Endpoint to be patched

Sample Response

{
  "endpoint_sid": "00bf8b25-1e20-4f80-8529-8448df32d71a",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "3rdParty",
  "type": "third_party",
  "voip_token": "ab72ad7a-568b-466e-9fd9-407de0313e36",
  "capacity": 0,
  "addresses": [
      {
          "ip": "15.1.12.6",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      },
      {
          "ip": "1.1.2.2",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      },
      {
          "ip": "2.2.2.3",
          "port": 5060,
          "direction": "any",
          "transport": "udp"
      }
  ],
  "attributes": {},
  "transformations": []
}

Attributes

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
voip_token opt string Endpoint authentication token
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
addresses ip string IP address
port opt integer Port. Default value is 5060
direction string Direction for this address = ['inbound', 'outbound', 'any (default)']
transport string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes key string Attribute key
value string Attribute value
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
accept, reject
action string Action to be executed for transformation:
accept, reject
operands array Value(s) to be used for "action"

Update an Existing Endpoint

This call performs a complete update of the Endpoint. This call can be used for both changing and removing values.
Note: For Mediator type = mediator, FlexML type = flexml, and Conference endpoints, only name and capacity fields are editable.

METHOD URL
PUT /endpoints/{endpoint_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"endpoint_sid": "00bf8b25-1e20-4f80-8529-8448df32d71a", "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5", "name": "3rdParty", "type": "third_party", "voip_token": "ab72ad7a-568b-466e-9fd9-407de0313e36", "capacity": 0, "addresses": [ {"ip": "1.1.2.2", "port": 5060, "transport": "udp" }, {"ip": "2.2.2.3", "port": 5060, "transport": "udp" } ], "attributes": {}, "transformations": []}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints/00bf8b25-1e20-4f80-8529-8448df32d71a'

Parameters

Parameter Data Type Description
endpoint_sid req string Endpoint secure ID
body req ... Attributes which need to be modified.

Sample Response

 {
  "endpoint_sid": "00bf8b25-1e20-4f80-8529-8448df32d71a",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "name": "3rdParty",
  "type": "third_party",
  "voip_token": "ab72ad7a-568b-466e-9fd9-407de0313e36",
  "capacity": 0,
  "addresses": [
      {
          "ip": "1.1.2.2",
          "port": 5060,
          "direction": "any"
          "transport": "udp"
      },
      {
          "ip": "2.2.2.3",
          "port": 5060,
          "direction": "any"
          "transport": "udp"
      }
  ],
  "attributes": {},
  "transformations": []
}

Attributes

Attribute Data Type Description
endpoint_sid opt string Endpoint secure ID
voip_token opt string Endpoint authentication token
name opt string Endpoint name
partner_sid opt string Secure ID of the Partner to whom this Endpoint belongs
addresses ip string IP address
port opt integer Port. Default value is 5060
direction string Direction for this address = ['inbound', 'outbound', 'any (default)']
transport string Protocol which this Address belongs to (udp – default, tcp)
capacity integer Maximum number of simultaneous calls (inbound and outbound)
attributes key string Attribute key
value string Attribute value
type string system_gateway - CarrierX gateway
third_party - Third Party endpoint
conference - Hosted Conference endpoint
mediator - Hosted Mediator endpoint
flexml - Hosted FlexML endpoint
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"





Trunk Groups

Trunk Groups are entities that consist of one or several Trunks. It is possible to create a Trunk Group with no Trunks, but no Trunk can be created apart from a Trunk Group.

Get Trunk Groups Matching the Specified Criteria

Shows the list of available Trunk Groups. If with_trunks is set to true, the call will return Trunk Groups with Trunks. If set to no value, or to false,

The number of displayed items will be limited by the limit/ offset values only. If the number of items exceeds the limit value, the has_more field in the response is set to true, pagination field suggests moving either to the next page or the previous one.

Alongside with the items, the GET request will return the following information:

 {
  "offset": 0,
  "limit": 10,
  "count": 10,
  "total": 541,
  "has_more": true,
  "pagination": {
      "next": "https://api.carrierx.com/core/v2/trunk_groups?limit=10&offset=10"
  },
Parameter Data Type Description
offset integer Amount of skipped items (as defined in the request)
limit integer Number of the returned items (as defined in the request)
count integer Number of items returned in the response.
count = limit – in case the ‘count’ value exceeds the defined ‘limit’
count < limit – in case number of the available items is less than defined ‘limit’
total integer Total amount of available items
has_more boolean Shows whether or not more items are available
pagination string The link leading to the next page if more items are available

METHOD URL
GET /trunk_groups

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups?with_trunks=true&offset=0&limit=10'

Parameters

Parameter Data Type Description
with_trunks boolean Whether or not display TrunkGroup with trunk(s)
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq Test
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

  {
  "trunk_group_sid": "d47bc93e-64a1-4726-9131-e5f0accb4e0a",
  "name": "pqa_03a",
  "partner_sid": "4710877d-ce91-41eb-a96d-f487d547d2b1",
  "routing_type": "failover",
  "routing_data": null,
  "soft_failure_cooldown": 120,
  "soft_failure_codes": "408;",
  "acls": [
    {
       "direction": "outbound",
       "voice_action_true": null,
       "voice_action_false": "reject503",
       "sms_action_true": null,
       "sms_action_false": null,
       "access_control_rules": [
           "e214f6ab-7184-425b-85a9-7991e598ae72",
           "5b76b65c-259f-46f4-b083-7d0c3d3c4de4"
       ]
   },
   {
       "direction": "outbound",
       "voice_action_true": null,
       "voice_action_false": "accept",
       "sms_action_true": null,
       "sms_action_false": null,
       "access_control_rules": [
          "2c36804d-6e93-40c3-959d-8f59ab43e03c",
          "fea69a86-aa25-4797-8826-7bb695d0d498"
      ]
    }
  ],
  "trunks": [
    {
      "name": "tr1",
      "codec": null,
      "trunk_sid": "c41f7a3c-e5c9-4fb9-835f-8423497edf20",
      "endpoint_sid": null,
      "in_capacity": 0,
      "out_capacity": 0,
      "call_type": "regular",
      "transformations": [],
  "transformations": [
    {
      "direction": "outbound",
      "action": "rewrite_from",
      "operands": [
          "45611",
          "15601213322"
      ]
    }
  ]
}

Note: if you need to find a trunk group with a particular trunk under it, you may filter results by the trunk name or the endpoint_sid value it is assigned to.

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/endpoints?offset=0&limit=10&filter=addresses.ip%20eq%20%22162.251.181.136%22'

Sample Response

  {
    "offset": 0,
    "limit": 10,
    "count": 1,
    "total": 1,
    "has_more": false,
    "pagination": {},
    "items": [
        {
            "endpoint_sid": "9fbfee56-5ded-4e65-a22c-697cd0331c16",
            "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
            "name": "Core Endpoint",
            "type": "system_gateway",
            "voip_token": null,
            "capacity": 0,
            "addresses": [
                {
                    "ip": "162.251.181.136",
                    "port": 5060,
                    "direction": "any",
                    "transport": "udp"
                }
            ],
            "attributes": {},
            "transformations": []
        }
    ]
}

Attributes

Attribute Data Type Description
trunk_group_sid opt string Trunk Group secure ID
name opt string Trunk Group name
partner_sid opt string Secure ID of the Partner to whom this Trunk Group belongs
routing_type string Routing type for trunks. Possible values:
failover, round_robin
routing_data object Additional routing data for trunks
soft_failure_cooldown string Time in seconds to wait if the Trunk is down
soft_failure_codes opt string SIP codes on the basis of which Trunk failure is defined, separated by ';'
acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
trunks trunk_sid opt string Trunk secure ID
name opt string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls; 0=unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls; 0=unlimited (default)
codec opt string Supported codecs
call_type string Call type. Possible values:
sip_only, regular, redirect_302
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Create a New Trunk Group

This will add a new Trunk Group with or without trunks. If no value is specified at the creation step, the name will be set to N/A value, and the partner_sid will be the secure ID of the currently logged in partner. If the routing_type is not specified, it will be automatically set to the default value failover. PATCH call.

If with trunks parameter is set to false,
Each Partner can control what calls can be placed or received with the help of Access Control Lists (ACL). Access Control List (ACL) consists of the list of Access Control Rules, i.e. single checks that determine the scope of data to be checked in SIP calls.
ACL’s can exist both on the Partner and the Trunk Group levels. On the Trunk Group level, ACLs are defined in acls. PATCH or PUT calls.

sms_action_true and sms_action_false define what action is to be executed for a particular ACL. Possible values are accept and reject.
voice_action_true and voice _action_false define what action is to be executed for a particular ACL. Possible values are accept, reject403, reject503.
Note: If either sms/voice_action_true or sms/voice_action_false is set to one of above values, the other one should be set to null. They cannot be set to some value simultaneously.

For example: voice_action_true:"accept", "voice_action_false":null.

METHOD URL
POST /trunks_groups

Sample URL


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

Parameters

Parameter Data Type Description
body req ... Body of the Trunk Group to be created
with_trunks boolean Whether or not create TrunkGroup with trunk(s)

Sample 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": []
}

Attributes

Attribute Data Type Description
trunk_group_sid opt string Trunk Group secure ID
name opt string Trunk Group name
partner_sid opt string Secure ID of the Partner to whom this Trunk Group belongs
routing_type string Routing type for trunks. Possible values:
failover, round_robin
routing_data object Additional routing data for trunks
soft_failure_cooldown string Time in seconds to wait if the Trunk is down
soft_failure_codes opt string SIP codes on the basis of which Trunk failure is defined, separated by ';'
acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
trunks trunk_sid opt string Trunk secure ID
name opt string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls; 0=unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls; 0=unlimited (default)
codec opt string Supported codecs
call_type string Call type. Possible values:
sip_only, regular, redirect_302
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Remove a Trunk Group

This will remove the existing Trunk Group. All Trunks that have been created under this Trunk Group will be also removed.

METHOD URL
DELETE /trunk_groups/{trunk_group_sid}

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/s6Da94-oxPcGxCGlvsPFuST-o3umYCMr'

Parameters

Parameter Data Type Description
trunk_group_sid req string Secure ID of the Trunk Group to be removed

Get a Trunk Group by SID

This call will return information for the Trunk Group which secure ID is specified. If with_trunks parameter is set to true, false value is provided.

METHOD URL
GET /trunk_groups/{trunk_group_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u : 'https://api.carrierx.com/core/v2/trunk_groups/.vwm9yyV4ffsttLGxndm4wuKiXc82.-h?with_trunks=true"
Make request

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "trunk_group_sid": ".vwm9yyV4ffsttLGxndm4wuKiXc82.-h",
  "name": "TrunkGroup8",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "routing_type": "failover",
  "routing_data": null,
  "soft_failure_cooldown": 120,
  "soft_failure_codes": "408;",
  "acls": [],
  "trunks": [],
  "transformations": []
}

Attribute Data Type Description
trunk_group_sid opt string Trunk Group secure ID
name opt string Trunk Group name
partner_sid opt string Secure ID of the Partner to whom this Trunk Group belongs
routing_type string Routing type for trunks. Possible values:
failover, round_robin
routing_data object Additional routing data for trunks
soft_failure_cooldown string Time in seconds to wait if the Trunk is down
soft_failure_codes opt string SIP codes on the basis of which Trunk failure is defined, separated by ';'
acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
trunks trunk_sid opt string Trunk secure ID
name opt string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls; 0=unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls; 0=unlimited (default)
codec opt string Supported codecs
call_type string Call type. Possible values:
sip_only, regular, redirect_302
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Patch Trunk Group

This call will do partial update of the Trunk Group. It can be used for changing Trunk Group attributes, adding ACLs and/or transformations. However, it can’t be applied for changing any of the Trunk attributes. Neither can it be used to add or to remove the Trunk ojects. If not done at the creation step, the new Trunk can be added with the Trunk API only.

On the Trunk Group level, ACLs are defined in acls attribute.
As well as on the Partner’s level, ACL’s cannot be shared between Trunk Groups, and have to be created specifically for each Trunk Group.
sms_action_true and sms_action_false define what action is to be executed for a particular ACL. Possible values are accept, reject.
voice_action_true and voice _action_false define what action is to be executed for a particular ACL. Possible values are accept, reject403, reject503.

Note: If either [sms/voice]_action_true or [sms/voice]_action_false is set to one of above values, the other one should be set to null. They cannot be set to some value simultaneously.
For example: "voice_action_true": "accept" "voice_action_false":null
"sms_action_true": null, "sms_action_false": "reject"

Arrays of complex objects (like transformations and acls) get totally replaced by the new values. If a PATCH call contains a transformation or acl object, it will totally replace the existing one if any. In order to add a new acl or transformation, send the request containing both - the existing object(s) and the one to be added.

Note: only parameters specified in the call will be updated. The other will preserce their current value.

METHOD URL
PATCH /trunk_groups/{trunk_group_sid}

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"transformations": [ { "direction": "outbound", "action": "rewrite_from", "operands": [ "9999", "18662911805" ] }]}" -u : https://api.carrierx.com/core/v2/trunk_groups/bOUF99CmufeCwMPanRThYPBayANjvbRL'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
body ... Body of the Trunk Group to be patched

Sample Response

 {
  "trunk_group_sid": "bOUF99CmufeCwMPanRThYPBayANjvbRL",
  "name": "TrunkGroup4",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "routing_type": "failover",
  "routing_data": null,
  "soft_failure_cooldown": 120,
  "soft_failure_codes": "408;",
  "acls": [],
  "transformations": [
      {
          "direction": "outbound",
          "action": "rewrite_from",
          "operands": [
              "9999",
              "18662911805"
          ]
      }
  ]
}

Attributes

Attribute Data Type Description
trunk_group_sid opt string Trunk Group secure ID
name opt string Trunk Group name
partner_sid opt string Secure ID of the Partner to whom this Trunk Group belongs
routing_type string Routing type for trunks. Possible values:
failover, round_robin
routing_data object Additional routing data for trunks
soft_failure_cooldown string Time in seconds to wait if the Trunk is down
soft_failure_codes opt string SIP codes on the basis of which Trunk failure is defined, separated by ';'
acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
trunks trunk_sid opt string Trunk secure ID
name opt string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls; 0=unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls; 0=unlimited (default)
codec opt string Supported codecs
call_type string Call type. Possible values:
sip_only, regular, redirect_302
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Update Trunk Group

Total update of the Trunk Group. Can be used for removing values for the specified Trunk Group. This call cannot be applied for adding/removing Trunks within a Trunk Group though. Any attempt to do so will be ignored. Only changes applicable to the Trunk Group object will be processed.

METHOD URL
UPDATE /trunk_groups/{trunk_group_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{ "trunk_group_sid": "bOUF99CmufeCwMPanRThYPBayANjvbRL\", "name": "TrunkGroup4", "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x", "routing_type": "failover", "routing_data": null, "soft_failure_cooldown": 120, "soft_failure_codes": "408;", "acls": [], "transformations": [ { "direction": "outbound", "action": "rewrite_from", "operands": [ "9999", "18662911805" ] } ] }" -u : 'https://api.carrierx.com/core/v2/trunk_groups/bOUF99CmufeCwMPanRThYPBayANjvbRL'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
body ... Body of the Trunk Group to be updated

Sample Response

 {
  "trunk_group_sid": "bOUF99CmufeCwMPanRThYPBayANjvbRL",
  "name": "TrunkGroup4",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "routing_type": "failover",
  "routing_data": null,
  "soft_failure_cooldown": 120,
  "soft_failure_codes": "408;",
  "acls": [],
  "transformations": [
      {
          "direction": "outbound",
          "action": "rewrite_from",
          "operands": [
              "9999",
              "18662911805"
          ]
      }
  ]
}

Attributes

Attribute Data Type Description
trunk_group_sid opt string Trunk Group secure ID
name opt string Trunk Group name
partner_sid opt string Secure ID of the Partner to whom this Trunk Group belongs
routing_type string Routing type for trunks. Possible values:
failover, round_robin
routing_data object Additional routing data for trunks
soft_failure_cooldown string Time in seconds to wait if the Trunk is down
soft_failure_codes opt string SIP codes on the basis of which Trunk failure is defined, separated by ';'
acls acl direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"
trunks trunk_sid opt string Trunk secure ID
name opt string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls; 0=unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls; 0=unlimited (default)
codec opt string Supported codecs
call_type string Call type. Possible values:
sip_only, regular, redirect_302
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"






Trunks

Each Trunk Group consists of one or multiple Trunks. Trunks cannot be created apart from the Trunk Groups. When searching for a particular Trunk, first you must define the Trunk Group it belongs to, for the search to run within the selected Trunk Group only.

Get Trunks Matching the Specified Criteria

Each Trunk Group consists of one or multiple Trunks. Trunks cannot be created apart from the Trunk Groups. When searching for a particular Trunk, fist you must define the Trunk Group it belongs for the search to run within the particular Trunk Group only.

METHOD URL
GET /trunk_groups/{trunk_group_sid}/trunks

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/cd143163-a22a-4e54-9348-a5e4a6d5d396/trunks?offset=0&limit=10'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq Test
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
          "name": "Trunk_0516_04_1",
          "codec": null,
          "trunk_sid": "15927485-7a3a-4abf-80cf-98dd2cd1d8d2",
          "endpoint_sid": null,
          "in_capacity": 0,
          "out_capacity": 0,
          "call_type": "regular",
          "transformations": []
      }

Attributes

Attribute Data Type Description
trunk_sid opt string Trunk secure ID
name string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls: 0 = unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls: 0 = unlimited (default)
codec string Supported codec
call_type integer Call Type:
  • 0 = SIP only
  • 1 = with media (default)
  • 2 = 302-redirect
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Create a New Trunk

This will add a new trunk to the selected Trunk Group, and connect it with the existing endpoint. If the endpoint_sid is not specified , the new trunk will remain unassigned. The CarrierX Endpoint secure ID will be assigned automatically when the new Trunk is created.
Trunk may reference an Endpoint as a whole, or be bound to a particular Endpoint address.
If endpoint_sid value is not defined at the creation step, the Trunk will relate to the entire Endpoint, i.e. all its configured addresses. routing_type if not specified will be set to the default failover value.

METHOD URL
POST /trunk_groups/{trunk_group_sid}/trunks

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name": "trunk01", "endpoint_sid": null}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/f3893c2c-90d2-46f5-917a-5dba613cab6d/trunks'

Parameters

Parameter Data Type Description
body req ... Body of the Trunk to be created

Sample Response

 {
  "name": "trunk01",
  "codec": null,
  "trunk_sid": "048eacb0-cfde-4755-b289-83be79011e45",
  "endpoint_sid": null,
  "in_capacity": 0,
  "out_capacity": 0,
  "call_type": "regular",
  "transformations": []
}

Attributes

Attribute Data Type Description
trunk_sid opt string Trunk secure ID
name string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls: 0 = unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls: 0 = unlimited (default)
codec string Supported codec
call_type integer Call Type:
  • 0 = SIP only
  • 1 = with media (default)
  • 2 = 302-redirect
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Remove a Trunk

This will remove one of the existing trunks.

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

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/188b8e36-728d-48f9-a253-2326352b85f5/trunks/mtid9.iwlPeZ7EU7ABGOHP4ieMStx.nl”

Parameters

Parameter Data Type Description
trunk_sid req string Secure ID of the Trunk to be removed

Get Trunk by SID

This will show detailed information for the selected Trunk.

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

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/f3893c2c-90d2-46f5-917a-5dba613cab6d/trunks/21efab69-ded1-4c71-adbe-10584587189c'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
trunk_sid req string Trunk secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "name": "tr1",
  "codec": null,
  "trunk_sid": "21efab69-ded1-4c71-adbe-10584587189c",
  "endpoint_sid": "601f0f9b-759f-485f-bc45-d1f919e8cab3",
  "in_capacity": 0,
  "out_capacity": 0,
  "call_type": "regular",
  "transformations": []
}

Attributes

Attribute Data Type Description
trunk_sid opt string Trunk secure ID
name string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls: 0 = unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls: 0 = unlimited (default)
codec string Supported codec
call_type integer Call Type:
  • 0 = SIP only
  • 1 = with media (default)
  • 2 = 302-redirect
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Patch a Trunk

This call performs a partial update of the Trunk. This call is not applicable for removing values.

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

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"name": "trunk_new_name", "endpoint_sid": null}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/f3893c2c-90d2-46f5-917a-5dba613cab6d/trunks/21efab69-ded1-4c71-adbe-10584587189c'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
trunk_sid req string Secure ID of the Trunk
body ... Body of the Trunk Group to be patched

Sample Response

 {
  "name": "trunk_new_name",
  "codec": null,
  "trunk_sid": "21efab69-ded1-4c71-adbe-10584587189c",
  "endpoint_sid": "601f0f9b-759f-485f-bc45-d1f919e8cab3",
  "in_capacity": 0,
  "out_capacity": 0,
  "call_type": "regular",
  "transformations": []
}

Attributes

Attribute Data Type Description
trunk_sid opt string Trunk secure ID
name string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls: 0 = unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls: 0 = unlimited (default)
codec string Supported codec
call_type integer Call Type:
  • 0 = SIP only
  • 1 = with media (default)
  • 2 = 302-redirect
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Update a Trunk

This call performs a complete update of the Trunk. This call can be used for removing values.

METHOD URL
UPDATE/td> /trunk_groups/{trunk_group_sid}/trunks/{trunk_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "name": "trunk_new_name", "codec": null, "trunk_sid": "21efab69-ded1-4c71-adbe-10584587189c", "endpoint_sid\": "601f0f9b-759f-485f-bc45-d1f919e8cab3", "in_capacity": 0, "out_capacity": 0, "call_type": "regular", "transformations": [] }' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/trunk_groups/f3893c2c-90d2-46f5-917a-5dba613cab6d/trunks/21efab69-ded1-4c71-adbe-10584587189c'

Parameters

Parameter Data Type Description
trunk_group_sid req string Trunk Group secure ID
trunk_sid string Trunk secure ID
body ... Body of the Trunk to be updated

Sample Response

 {
  "name": "trunk_new_name",
  "codec": null,
  "trunk_sid": "21efab69-ded1-4c71-adbe-10584587189c",
  "endpoint_sid": "601f0f9b-759f-485f-bc45-d1f919e8cab3",
  "in_capacity": 0,
  "out_capacity": 0,
  "call_type": "regular",
  "transformations": []
}

Attributes

Attribute Data Type Description
trunk_sid opt string Trunk secure ID
name string Trunk name
endpoint_sid opt string Secure ID of the Endpoint this Trunk belongs to
in_capacity opt integer Max number of inbound simultaneous calls: 0 = unlimited (default)
out_capacity opt integer Max number of outbound simultaneous calls: 0 = unlimited (default)
codec string Supported codec
call_type integer Call Type:
  • 0 = SIP only
  • 1 = with media (default)
  • 2 = 302-redirect
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"





DIDs

After Trunks and Trunk Groups have been created, you may move to renting DIDs. Check inventory for the available phone numbers and their capabilities. When renting a new DID, ensure it is connected directly with the existing Trunk Group. If no Trunk Group is specified in the POST call, DID will remain unassigned.

Get DIDs Matching the Specified Criteria

Shows the list of DIDs that have already been rented. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true, pagination field suggests moving either to the next page or the previous one.

Alongside with the items, the GET request will return the following information:

 {
  "offset": 0,
  "limit": 10,
  "count": 10,
  "total": 541,
  "has_more": true,
  "pagination": {
      "next": "https://api.carrierx.com/core/v2/dids?limit=10&offset=10"
  }
Parameter Data Type Description
offset integer Amount of skipped items (as defined in the request)
limit integer Number of the returned items (as defined in the request)
count integer Number of items returned in the response.
count = limit – in case the ‘count’ value exceeds the defined ‘limit’
count < limit – in case number of the available items is less than defined ‘limit’
total integer Total amount of available items
has_more boolean Shows whether or not more items are available
pagination string The link leading to the next page if more items are available

METHOD URL
GET /dids

Sample URL


curl -X GET --header 'Accept: application/json' –u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids?offset=0&limit=10&filter=trunk_group_sid%20ne%20null'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
info.country_code eq "USA" and info.capabilities bit 4 returns all DIDs with country_code= 4(100), 5(101), 6(110), 7(111), 12(1100), 13(1101) etc
order string Specifies order of items in the response: asc, desc

Example:
info.country_code desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "did_sid": "1b653875-01f0-4219-8f85-bba8d142bacb",
  "phonenumber": "15162065290",
  "in_country_format": "(516) 206-5290",
  "international_format": "+1 516-206-5290",
  "capabilities": 7,
  "country_code": "USA",
  "state": null,
  "locality": null,
  "price": "0.6",
  "partner_sid": "8ced9c69-da68-4bf0-96c3-eb95eec2b95c",
  "trunk_group_sid": "8c8735ed-e69c-4748-be8b-d22d744baa69",
  "callback_url": null,
  "attributes": {},
  "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Rent a New DID

Use this call to assign a new DID to your Partner account. Upon assignment, the DID will be removed from the inventory pool of available numbers and will be associated to the Partner account until it is removed. You can pick out a phone number belonging to a certain country or possessing properties that shows its ability to receive calls or messages. All phone numbers come in two formats: local and international.

METHOD URL
POST /dids

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"phonenumber":"15187778065", "callback_url":""}' 'https://api.carrierx.com/core/v2/dids'

Parameters

Parameter Data Type Description
body req DID object Body of the DID to be created

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Remove DID

This call will remove the DID from the Partner. Afterwards, the number will automatically be added to a “cool-down” pool and will no longer be retrievable from the general pool of DIDs until the cool off period has expired.

METHOD URL
DELETE /dids/{did_sid}

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/fMDS950WI-eD6UJSLM2nnqDD4Q1vkEod'

Parameters

Parameter Data Type Description
did_sid req string Secure ID of the DID to be removed

Get DID by SID

This call will allow you to obtain detailed information about the DIDs associated to a specific SID.

METHOD URL
GET /dids/{did_sid}

Sample URL



curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/d5b7cf92-2fb2-4e27-abcb-d345a4137161'

Parameters

Parameter Data Type Description
did_sid req string Sercure ID of the DID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Patch DID

This call performs a partial update of the DID. Not applicable for removing values.

METHOD URL
PATCH /dids/{did_sid}

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"attributes":{"attribute1":"value1"}}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/8oD290nJavb2kJX4d8hV.hcP.AO3Xcn.'

Parameters

Parameter Data Type Description
did_sid req string Sercure ID of the DID
body req ... Body of the DID to be patched

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Update DID

This call performs a total update of the DID. This can be used for removing values previously configured.

METHOD URL
PUT /dids/{did_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d ' {"did_sid": "8oD290nJavb2kJX4d8hV.hcP.AO3Xcn.", "phonenumber": "15187778065", "in_country_format": "(518) 777-8065", "international_format": "+1 518-777-8065", "capabilities": 7, "country_code": "USA", "state": "NY", "locality": null, "price": "0.6", "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee", "trunk_group_sid": null, "callback_url": null, "attributes": {}, "transformations": [] }' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/8oD290nJavb2kJX4d8hV.hcP.AO3Xcn.'

Parameters

Parameter Data Type Description
did_sid req string Secure id of the specific item which is being updated
body req ... Body of the DID to be updated

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Browse DID Inventory Matching the Specified Criteria

Pool of numbers available for renting. Allows searching for the phone number matching certain country, format, or required capabilities value.

Alongside with the items, the GET request will return the following information:

{
  "offset": 0,
  "limit": 10,
  "count": 10,
  "total": null,
  "has_more": true,
  "pagination": {
      "next": "https://api.carrierx.com/core/v2/dids/inventory?limit=10&offset=10"
  },
Parameter Data Type Description
offset integer Amount of skipped items (as defined in the request)
limit integer Number of the returned items (as defined in the request)
count integer Number of items returned in the response.
count = limit – in case the ‘count’ value exceeds the defined ‘limit’
count < limit – in case number of the available items is less than defined ‘limit’
total integer Total amount of available items
has_more boolean Shows whether or not more items are available
pagination string The link leading to the next page if more items are available

METHOD URL
GET /dids/inventory

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/inventory?offset=0&limit=10"

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is set to 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is set to 10
filter string SQL like query to limit amount of output eq, ne, gt, gte/ge, lt, lte/le, startswith, endswith, contains, regex/regexp,
bit operator is available for capabilities field.

Example:
country_code eq “USA” and capabilities bit 3 returns all DIDs with country_code = USA and capabilities with bit mask ends on 11
(i.e. following numbers: 3, 7, 11, 15, etc)

Example:
phonenumber like "1209%"
phonenumber like "4209%" and country_code eq "ITA"
order string Specifies order of items in the response: asc, desc

Example:
country_code desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Get DID Inventory by SID

This call will return a single instance of the DID inventory which secure ID is specified.

METHOD URL
GET /dids/inventory/{did_sid}

Sample URL


curl -X GET --header "Accept: application/json" --header -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/inventory/c9Ua89icuONvDvs0kvlNaPzMLDXwuEYJ'

Parameters

Parameter Data Type Description
did_sid string DID secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
    "did_sid": "d5b7cf92-2fb2-4e27-abcb-d345a4137161",
    "phonenumber": "16507951052",
    "in_country_format": "(650) 795-1052",
    "international_format": "+1 650-795-1052",
    "capabilities": 7,
    "country_code": "USA",
    "state": "CA",
    "locality": null,
    "price": "0.6",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "trunk_group_sid": "1b6f6a1d-de00-4520-b443-38ceb521f2ed",
    "callback_url": null,
    "attributes": {},
    "transformations": []
}

Attributes

Attribute Data Type Description
did_sid opt string DID secure ID
phonenumber string Phone number for this DID in E.164 format
in_country_format string DID in a national format
international_format string DID in an international format
capabilities integer This field is an Integer representation of a Bit mask with the following core values:
1* = SMS IN (*represents 1 in a bit mask)
2* = SMS OUT (*represents 10 a in bit mask)
4* = VOICE (*represents 100 in a bit mask)
Example:
"capabilities bit 3”
returns results for numbers with SMS capabilities = 1+2=3
"capabilities bit 7”
returns results for numbers with both SMS and VOICE capabilities = 1+2+4 = 7
country_code string ISO 3166-1 alpha-3 code of this DID, given automatically
state string State/province of this DID
locality string Locality/city of this DID
price integer Price of this DID
partner_sid string Secure ID of the Partner whom DID belongs to
trunk_group_sid string Secure ID of the Trunk Group which this DID belongs to.
callback_url string Callback URL to receive events for SMS
attributes array Additional attributes
transformations direction string Direction for transformation:
inbound, outbound, any
action string Action to be executed for transformation:
rewrite_to, rewrite_from
operands array Value(s) to be used for "action"

Browse Numbering Plan Area (NPA) matching the specified criteria and their inventory levels

This call performs a search by numbering plan area (NPA) and obtains a match based on the specified criteria. Responses can also include inventory levels if specified.

METHOD URL
GET /dids/coverage

Sample URL


curl -X GET --header 'Accept: application/json' --header -u [your_user_name]:[your_password] https://api.carrierx.com/core/v2/dids/coverage?offset=0&limit=10&group_by=state'

Parameters

Parameter Data Type Description
group_by string Grouping. Allowable values: country, state, locality, npa, npa_nxx. Multiple values are not allowed
offset integer Amount of items to be skipped in the response. Default value is set to 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is set to 10
filter string SQL like query to limit amount of output eq, ne, gt, gte/ge, lt, lte/le, startswith, endswith, contains, regex/regexp,

Example:
npa eq 240
order string Specifies order of items in the response: asc, desc

Example:
state asc, npa desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

  {
          "key": "IL",
          "count": 116
      },
      {
          "key": "MD",
          "count": 8
      },
      {
          "key": "CA",
          "count": 689
      }

Attributes

Attribute Data Type Description
key string Value by which the phone numbers are grouped in the response
count integer Total quantity of phone numbers for the given npa



Get Rates Matching the Specified Criteria

This call performs a search of existing rates matching the defined criteria.

METHOD URL
GET /dids/rates

Sample URL


curl -X GET --header 'Accept: application/json' --header -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/rates?offset=0&limit=10"

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is set to 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is set to 10
filter string SQL like query to limit amount of output eq, ne, gt, gte/ge, lt, lte/le, startswith, endswith, contains, regex/regexp,

Example:
price eq 5
order string Specifies order of items in the response: asc, desc

Example:
price desc

The default order is ascending
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "offset": 0,
  "limit": 10,
  "total": 10,
  "has_more": false,
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "effective_date": "2016-01-01T00:00:00.000Z",
  "active": "yes",
  "pagination": {},
  "items": [
      {
          "prefix": 1565,
          "price": "1",
          "country_code": "USA"
      }
  ]
}

Attributes

Attribute Data Type Description
country_code opt string ISO 3166-1 alpha-3 code of this Rate
prefix opt string Number prefix for this did
price opt number Price for this Rate

Get Rates by Phone Number

This call will return the existing rates for the specified phone number.

METHOD URL
GET /dids/rates/{phonenumber}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/dids/rates/18004561252?offset=0&limit=10"

Parameters

Parameter Data Type Description
phonenumber req string Phone number
offset integer Amount of items to be skipped in the response. Default value is set to 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is set to 10
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
   "prefix": 180,
   "price": "1",
   "country_code": "USA"
}

Attributes

Attribute Data Type Description
country_code opt string ISO 3166-1 alpha-3 code of this Rate
proefix opt string Number prefix for this did
price opt number Price for this Rate





SMS

Sending SMS is one of the most frequent tasks that can be run with this IP. You can put in queue several messages to be sent from one telephone number, and they all will be sent out successively. If you need to send several messages at a time, you may need to rent several DIDs. A POST request will later be made to your Callback URL with an appropriate status change value.


Get Message DRs Matching the Specified Criteria

Shows the list of Message detailed reports (DRs) for inbound and outbound messages. If no filter is specified, the number of displayed items will be limited by the “limit”/”offset” values only. If the number of items exceeds the “limit” value, the “has_more”: in the response is set to “true”, and the “pagination” field suggests moving either to the next page or the previous one.

METHOD URL
GET /sms/message_drs

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/message_drs?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
direction eq "outbound" and mcc eq 0
order string Specifies order of items in the response: asc, desc

Example:
status desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
    "dr_sid": "03fed25a-274d-4e9a-8120-1454c63f7b23",
    "version": null,
    "type": "sms",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "direction": "outbound",
    "date_insert": "2018-04-11T10:45:00.000Z",
    "date_start": "2018-04-11T10:45:00.000Z",
    "date_stop": "2018-04-11T13:45:00.000Z",
    "status": "delivered",
    "mcc": 0,
    "mnc": 0,
    "message_segments": 1,
    "price": "0.005",
    "number_billing": "17208209039",
    "number_external": "79200207571",
    "number_src": "17208209039",
    "number_dst": "79200207571",
    "message": "test message"
 }

Attributes

Attribute Data Type Description
message string Message body
status opt string Status of the message DR:
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
message_segments opt string Quantity of 160-symbols segments of message
dr_sid opt string Secure ID of the record
version opt string Version of the DR as it comes from the resource
type opt string Type of the DR. Possible values:
  • telecom
  • sms
  • conference
  • application
direction opt string Possible values:
  • inbound - incoming call or sms
  • outbound - outgoing call or sms
equipment_id string String to identify equipment received from the resource
number_src opt string Source number. It is calling number in the case of outbound direction or called number in the case of inbound
number_dst opt string Destination number. It is called number in the case of outbound direction or calling number in the case of inbound
date_insert opt string Date when the DR was inserted into the database
date_start opt string Date and time of the call start or sms creation
date_stop opt string Date and time of the call drop or sms delivering (with any status)
owner_sid opt string Partner SID of responsible party (shall not be null). In the case of inbound direction should contain a partner for number_dst (we shall have number_dst in the system in this case)
other_sid opt string Partner SID of other side of the call. Can be null for outbound direction for call or SMS to number outside of our system
price opt string Price for the DR
duration opt integer Overall call duration in seconds ( date_stop - date_start);
duration_audio opt integer Audio call duration in seconds; always 0 for SMS
duration_video opt integer Video call duration in seconds; always 0 for SMS
duration_data opt integer Data call duration in seconds (for example, Screen Sharing seconds); always 0 for SMS
disconnect_originator opt string Originator who dropped the call; null for sms
disconnect_cause opt string ISDN code of call termination
disconnect_reason opt string Specific disconnect reason received from the resource

Get Message DR by SID

This call will retrieve data for the single DR which secure ID is specified.

METHOD URL
GET /sms/message_drs/{dr_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/message_drs/03fed25a-274d-4e9a-8120-1454c63f7b23'

Parameters

Parameter Data Type Description
message_sid req string Secure ID of the message DR
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
    "dr_sid": "03fed25a-274d-4e9a-8120-1454c63f7b23",
    "version": null,
    "type": "sms",
    "partner_sid": "6feb0f8b-f104-4445-8db8-593c5e5cb7ee",
    "direction": "outbound",
    "date_insert": "2018-04-11T10:45:00.000Z",
    "date_start": "2018-04-11T10:45:00.000Z",
    "date_stop": "2018-04-11T13:45:00.000Z",
    "status": "delivered",
    "mcc": 0,
    "mnc": 0,
    "message_segments": 1,
    "price": "0.005",
    "number_billing": "17208209039",
    "number_external": "79200207571",
    "number_src": "17208209039",
    "number_dst": "79200207571",
    "message": "test message"
 }

Attributes

Attribute Data Type Description
message string Message body
status opt string Status of the message DR:
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
message_segments opt string Quantity of 160-symbols segments of message
dr_sid opt string Secure ID of the record
version opt string Version of the DR as it comes from the resource
type opt string Type of the DR. Possible values:
  • telecom
  • sms
  • conference
  • application
direction opt string Possible values:
  • inbound - incoming call or sms
  • outbound - outgoing call or sms
equipment_id string String to identify equipment received from the resource
number_src opt string Source number. It is calling number in the case of outbound direction or called number in the case of inbound
number_dst opt string Destination number. It is called number in the case of outbound direction or calling number in the case of inbound
date_insert opt string Date when the DR was inserted into the database
date_start opt string Date and time of the call start or sms creation
date_stop opt string Date and time of the call drop or sms delivering (with any status)
owner_sid opt string Partner SID of responsible party (shall not be null). In the case of inbound direction should contain a partner for number_dst (we shall have number_dst in the system in this case)
other_sid opt string Partner SID of other side of the call. Can be null for outbound direction for call or SMS to number outside of our system
price opt string Price for the DR
duration opt integer Overall call duration in seconds ( date_stop - date_start);
duration_audio opt integer Audio call duration in seconds; always 0 for SMS
duration_video opt integer Video call duration in seconds; always 0 for SMS
duration_data opt integer Data call duration in seconds (for example, Screen Sharing seconds); always 0 for SMS
disconnect_originator opt string Originator who dropped the call; null for sms
disconnect_cause opt string ISDN code of call termination
disconnect_reason opt string Specific disconnect reason received from the resource

Get Messages Matching the Specified Criteria

Shows the list of inbound and outbound messages. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true.

METHOD URL
GET /sms/messages

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/messages?offset=0&limit=10&filter=direction%20eq%20inbound'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
direction eq "outbound" and mcc eq 0
order string Specifies order of items in the response: asc, desc

Example:
status desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "message_sid": "580e262d-6384-41bd-a50f-07325326a003",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "message": "Sent from your  trial account - Thanks for the message.",
  "direction": "inbound",
  "date_created": "2016-10-11T10:27:47.000Z",
  "date_status_changed": "2016-10-11T10:27:47.000Z",
  "from_did": "12039301099",
  "to_did": "17208209016",
  "status": "received",
  "mcc": null,
  "mnc": null,
  "message_segments": 2,
  "price": "0"
}

Attributes

Attribute Data Type Description
message_sid opt string Message secure ID
partner_sid opt string Secure ID of the Partner to whom this message belongs
message opt string Message text
direction string Direction of message
  • inbound
  • outbound
date_created string Date when the message was created
date_completed string Date when the message was sent
from_did string Phone number of the message originator in E.164 format
to_did string Phone number of the recipient in E.164 format
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
price opt string Message charge

Send a New Message

This call will send an sms from the rented DID.

METHOD URL
POST /sms/messages

Sample URL


curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --header 'Accept: application/json' -d "from_did=15162065008&to_did=15162065010&message=Message%207" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/messages'

Parameters

Parameter Data Type Description
from_did req string Phone number of the message originator in E.164 format
to_did string Phone number of the recipient in E.164 format
message string Text of the message

Sample Response

 {
"message_sid": "JJao9y10h-c29qiiz1Ck-cECTiInAFjS",
"partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
"message": "Message 7",
"direction": "outbound",
"date_created": "2016-02-08T12:38:49.000Z",
"date_completed": null,
"from_did": "15162065008",
"to_did": "15162065010",
"status": "queued",
"mcc": null,
"mnc": null,
"message_segments": 1,
"price": null
}

Attributes

Attribute Data Type Description
message_sid opt string Message secure ID
partner_sid opt string Secure ID of the Partner to whom this message belongs
message opt string Message text
direction string Direction of message
  • inbound
  • outbound
date_created string Date when the message was created
date_completed string Date when the message was sent
from_did string Phone number of the message originator in E.164 format
to_did string Phone number of the recipient in E.164 format
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
price opt string Message charge

Get Message by SID

This call will return information for a single Partner whose secure ID is used to retrieve the criteria.

METHOD URL
GET /sms/messages/{sms_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] "https://api.carrierx.com/core/v2/sms/messages/kIvH91pJBPfQV.dVwTnpFYFnKMsm1ASz'

Parameters

Parameter Data Type Description
message_sid req string Message secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"message_sid": "kIvH91pJBPfQV.dVwTnpFYFnKMsm1ASz",
"partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
"message": "Message 6",
"direction": "outbound",
"date_created": "2016-02-08T06:52:46.000Z",
"date_completed": "2016-02-08T06:52:48.000Z",
"from_did": "15162065008",
"to_did": "15162065009",
"status": "outbound",
"mcc": null,
"mnc": null,
"message_segments": 1,
"price": null
}

Attributes

Attribute Data Type Description
message_sid opt string Message secure ID
partner_sid opt string Secure ID of the Partner to whom this message belongs
message opt string Message text
direction string Direction of message
  • inbound
  • outbound
date_created string Date when the message was created
date_completed string Date when the message was sent
from_did string Phone number of the message originator in E.164 format
to_did string Phone number of the recipient in E.164 format
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
price opt string Message charge

Get Outbound Rates Matching the Specified Criteria

Shows the list of outbound rates for a particular partner. If no partner is defined in the filter, the rates will be shown for the currently logged in Master Account.

METHOD URL
GET /sms/rates/outbound

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/rates/outbound?filter=partner_sid%20eq%20%22c9Ua99icuPdvDvvykvlNaPzMLDXwuEYJ%22%20and%20effective_date%20le%20%222015-02-28T00%3A00%3A00.000Z%22'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
price ge "1"
order string Specifies order of items in the response: asc, desc

Example:
operator desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response


Sample Response

 {
"offset": 0,
"limit": 10,
"total": 1,
"has_more": false,
"partner_sid": "c9Ua99icuPdvDvvykvlNaPzMLDXwuEYJ",
"effective_date": "2015-02-01T00:00:00.000Z",
"active": "no",
"items": [
   {
     "mcc": 0,
     "mnc": 0,
     "price": "1",
     "country_code": "USA",
     "operator": "CX1 01-FEB-15",
     "network": "CX1 01-FEB-15"
   }
 ]
}

Attributes

Attribute Data Type Description
country_code opt integer ISO 3166-1 alpha-3 code of this rate
operator opt string Operator name for this rate
network opt string Network name for this rate
mcc opt integer Mobile Country Code for this rate
mnc opt integer Mobile Network Code for this rate
price opt string The amount billed for the message

Send a New Verification Message

This will send a message with a unique code to another phone number. If you want to personalize your message, you may enter any text into the message field. The default text is "Your verification code is"

METHOD URL
POST /sms/verification

Sample URL


curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --header 'Accept: application/json' -d "from_did=17208209016&to_did=17256481234&message=Your%20verification%20code%20is%20" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/verification'

Parameters

Parameter Data Type Description
from_did req string Phone number of the message originator in E.164 format
to_did req string Phone number of the recipient in E.164 format
message string Message to be shown before the unique code. If remains epmty, only the code will be sent out.

Sample Response

{
  "message_sid": "cbc90eaf-2e33-4383-8edd-e32cc1826fd3",
  "partner_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "message": "681257",
  "direction": "outbound",
  "date_created": "2016-10-13T14:58:01.000Z",
  "date_status_changed": null,
  "from_did": "17208209016",
  "to_did": "17256481234",
  "status": "queued",
  "mcc": null,
  "mnc": null,
  "message_segments": 1,
  "price": null
}

Attributes

Attribute Data Type Description
message_sid opt string Message secure ID
partner_sid opt string Secure ID of the Partner to whom this message belongs
message opt string Message text
direction string Direction of message
  • inbound
  • outbound
date_created string Date when the message was created
date_completed string Date when the message was sent
from_did string Phone number of the message originator in E.164 format
to_did string Phone number of the recipient in E.164 format
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving
  • received
  • delivered
  • undelivered
  • failed
  • internal_error
  • timed_out
mcc opt integer Mobile country code
mnc opt integer Mobile network code
price opt string Message charge





Push

Get Applications Matching the Specified Criteria

This call will return the list of applications used for pushing notifications onto devices.

METHOD URL
GET /push/applications

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
google_id eq 'com.yourapp'
order string Specifies order of items in the response: asc, desc

Example:
status desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
          "name": "ReadyOrNot",
          "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f",
          "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
          "google_id": null,
          "google_key": "AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY",
          "apns_id": null,
          "apns_p12": "MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCCDU8ECCB"
          "apns_p12_password": "0000"
      }

Attributes

Attribute Data Type Description
name string Name of the item
application_sid string Application secure ID
partner_sid string Partner secure ID
google_id string Google Push Messaging Application ID
google_key string Google Push Messaging auth key
apns_id string Apple Push Messaging Application ID
apns_p12 string Apple Push Notification P12 certificate, encoded to Base64
apns_p12_password string Passphrase to Apple Push Notification P12 certificate

Add a New Application to Send Push

This call will create a new application for sending out push notifications.

METHOD URL
POSTt /push/applications

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"google_id":"", "google_key":"AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY", "apns_id":"", "apns_p12":"MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCCDU8ECCB", "apns_p12_password":"0000"}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications'

Parameters

Parameter Data Type Description
body req object Body of the application object to be created

Sample Response

 {
          "name": "ReadyOrNot",
          "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f",
          "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
          "google_id": null,
          "google_key": "AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY",
          "apns_id": null,
          "apns_p12": "MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCCDU8ECCB",
          "apns_p12_password": "0000"
      }

Attributes

Attribute Data Type Description
name string Name of the item
application_sid string Application secure ID
partner_sid string Partner secure ID
google_id string Google Push Messaging Application ID
google_key string Google Push Messaging auth key
apns_id string Apple Push Messaging Application ID
apns_p12 string Apple Push Notification P12 certificate, encoded to Base64
apns_p12_password string Passphrase to Apple Push Notification P12 certificate

Remove Application

This call will remove application which secure ID is specified. Note: deletion of application will remove the device where it has been installed

METHOD URL
DELETE /push/applications/{application_sid}

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications/dc8c2e59-550d-46d2-a072-667a6926a35f'

Parameters

Parameter Data Type Description
application_sid string Secure ID of the application to be removed

Get Application by SID

This call will return information on a single application instance which secure ID is specified.

METHOD URL
GET /push/applications/{application_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications/dc8c2e59-550d-46d2-a072-667a6926a35f'

Parameters

Parameter Data Type Description
application_sid string Application secure ID
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
          "name": "ReadyOrNot",
          "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f",
          "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
          "google_id": null,
          "google_key": "AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY",
          "apns_id": null,
          "apns_p12": "MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCCDU8ECCB",
          "apns_p12_password": "0000"
      }

Attributes

Attribute Data Type Description
name string Name of the item
application_sid string Application secure ID
partner_sid string Partner secure ID
google_id string Google Push Messaging Application ID
google_key string Google Push Messaging auth key
apns_id string Apple Push Messaging Application ID
apns_p12 string Apple Push Notification P12 certificate, encoded to Base64
apns_p12_password string Passphrase to Apple Push Notification P12 certificate

Patch Application

This call will partially update the existing application object which ID is specified. Note: only parameters specified in the call will be updated. The other will preserce their current value.

METHOD URL
PATCH /push/applications/{application_sid}

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"google_id":"456sdf4654", "google_key":"", "apns_id":"123121", "apns_p12":"", "apns_p12_password":”126115991100"}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications/dc8c2e59-550d-46d2-a072-667a6926a35f'

Parameters

Parameter Data Type Description
application_sid req string Application secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
          "name": "ReadyOrNot",
          "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f",
          "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
          "google_id": “456sdf4654”,
          "google_key": null,
          "apns_id": null,
          "apns_p12": null,
          "apns_p12_password": "123121"
      }

Attributes

Attribute Data Type Description
name string Name of the item
application_sid string Application secure ID
partner_sid string Partner secure ID
google_id string Google Push Messaging Application ID
google_key string Google Push Messaging auth key
apns_id string Apple Push Messaging Application ID
apns_p12 string Apple Push Notification P12 certificate, encoded to Base64
apns_p12_password string Passphrase to Apple Push Notification P12 certificate

Update Application

This call will fully update the existing application object which ID is specified. This call can be used to remove values.

METHOD URL
PUT /push/applications/{application_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{ "name": "ReadyOrNot", "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f", "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x", "google_id": null, "google_key": "AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY", "apns_id": null, "apns_p12": "MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCC", "apns_p12_password": "0000" }" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/applications/dc8c2e59-550d-46d2-a072-667a6926a35f'

Parameters

Parameter Data Type Description
application_sid integer Application secure ID
body object Body of the application object to be updated


Sample Response

 {
  "name": "ReadyOrNot",
  "application_sid": "dc8c2e59-550d-46d2-a072-667a6926a35f",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "google_id": null,
  "google_key": "AIzaSyBI0SLeUVt4F1J7edz7CEK3mWNMpiqumXY",
  "apns_id": null,
  "apns_p12": "MIINlwIBAzCCDV4GCSqGSIb3DQEHAaCC”,
  "apns_p12_password": "0000"
}

Attributes

Attribute Data Type Description
name string Name of the item
application_sid string Application secure ID
partner_sid string Partner secure ID
google_id string Google Push Messaging Application ID
google_key string Google Push Messaging auth key
apns_id string Apple Push Messaging Application ID
apns_p12 string Apple Push Notification P12 certificate, encoded to Base64
apns_p12_password string Passphrase to Apple Push Notification P12 certificate

Get Devices Matching the Specified Criteria

This call will return the list of applications used for pushing notifications onto devices

METHOD URL
GET /push/devices

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/devices?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
type eq 'android'
order string Specifies order of items in the response: asc, desc

Example:
name desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
          "device_sid": "19ad9d8b-1fd3-4313-a8c9-0c07c9138a9a",
          "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e",
          "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce",
          "type": "ios",
          "environment": "development",
          "os_version": null,
          "application_version": "0.0.10",
          "token": "bc7b2925d7f2847aa2b1eac52af2705f3af90050451f38013975a64e889"
      }

Attributes

Attribute Data Type Description
device_sid string Device secure ID
application_sid string Application secure ID installed on the device
partner_sid string Partner secure ID
type string Type of the device:
  • inbound
  • android
token string Push Notification identifying token from Google or Apple
os_version string Device operating system version
application_version string Version of the application on the device
environment string Environment to be used to send push, applicable to Apple Push Notification. Possible values:
  • development
  • production

Add a New Device to Send Push

This call will create a new application for sending out push notifications. “environment" value will be set to "production" if not specified otherwise.

METHOD URL
POST /push/devices

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"application_sid":"dc8c2e59-550d-46d2-a072-667a6926a35f", "type":"ios", "token":"1234565468797", "os_version":"", "application_version":""}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/devices'

Parameters

Parameter Data Type Description
body object Body of the device object to be created

Sample Response

 {
  "device_sid": "0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d",
  "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e",
  "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce",
  "type": "ios",
  "environment": "production",
  "os_version": "",
  "application_version": "",
  "token": "1234567891"
}

Attributes

Attribute Data Type Description
device_sid string Device secure ID
application_sid string Application secure ID installed on the device
partner_sid string Partner secure ID
type string Type of the device:
  • inbound
  • android
token string Push Notification identifying token from Google or Apple
os_version string Device operating system version
application_version string Version of the application on the device
environment string Environment to be used to send push, applicable to Apple Push Notification. Possible values:
  • development
  • production

Remove Device

This call will remove device which secure ID is specified.

METHOD URL
DELETE /push/devices/{device_sid}

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/devices/ bd846a2c-1970-47af-95fa-e59d64ec02fa'

Parameters

Parameter Data Type Description
device_sid integer Secure ID of the device to be removed

Get Device by SID

This call will return information on a single device instance which secure ID is specified.

METHOD URL
GET /push/devices/{device_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/push/devices/ bd846a2c-1970-47af-95fa-e59d64ec02fa'

Parameters

Parameter Data Type Description
device_sid string Device secure ID
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
  "device_sid": "0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d",
  "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e",
  "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce",
  "type": "ios",
  "environment": "production",
  "os_version": null,
  "application_version": null,
  "token": "1234567891"
}

Attributes

Attribute Data Type Description
device_sid string Device secure ID
application_sid string Application secure ID installed on the device
partner_sid string Partner secure ID
type string Type of the device:
  • ios
  • android
token string Push Notification identifying token from Google or Apple
os_version string Device operating system version
application_version string Version of the application on the device
environment string Environment to be used to send push, applicable to Apple Push Notification. Possible values:
  • development
  • production

Patch Device

This call will partially update the existing device object which ID is specified. Note: only parameters specified in the call will be updated. The other will preserce their current value.

METHOD URL
PATCH /push/devices/{device_sid}

Sample URL


curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"type":"android"}" -u : 'https://api.carrierx.com/core/v2/push/devices/0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d'

Parameters

Parameter Data Type Description
device_sid string Device secure ID
body string Feilds to be updated

Sample Response

 {
  "device_sid": "0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d",
  "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e",
  "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce",
  "type": "android",
  "environment": "production",
  "os_version": null,
  "application_version": null,
  "token": "1234567891"
}

Attributes

Attribute Data Type Description
device_sid string Device secure ID
application_sid string Application secure ID installed on the device
partner_sid string Partner secure ID
type string Type of the device:
  • ios
  • android
token string Push Notification identifying token from Google or Apple
os_version string Device operating system version
application_version string Version of the application on the device
environment string Environment to be used to send push, applicable to Apple Push Notification. Possible values:
  • development
  • production

Update Device

This call will fully update the existing device object which ID is specified. This call can be used to remove values.

METHOD URL
PUT /push/devices/{device_sid}

Sample URL


curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --d "{ "device_sid": "0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d", "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e", "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce", "type": "android", "environment": "production", "os_version": null, "application_version": null, "token": "1234567891" }" 'https://api.carrierx.com/core/v2/push/devices/0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d'

Parameters

Parameter Data Type Description
device_sid string Device secure ID
body object Body of the application object to be updated

Sample Response

 {
  "device_sid": "0ca5ba6f-fa47-4807-8106-cfb9a4f8bb1d",
  "application_sid": "1a92f8b6-05d0-480a-a9cd-3a5a1a50932e",
  "partner_sid": "fa0d7b84-bce7-4aa4-a4ba-987d078117ce",
  "type": "android",
  "environment": "production",
  "os_version": null,
  "application_version": null,
  "token": "1234567891"
}

Attributes

Attribute Data Type Description
device_sid string Device secure ID
application_sid string Application secure ID installed on the device
partner_sid string Partner secure ID
type string Type of the device:
  • ios
  • android
token string Push Notification identifying token from Google or Apple
os_version string Device operating system version
application_version string Version of the application on the device
environment string Environment to be used to send push, applicable to Apple Push Notification. Possible values:
  • development
  • production

Send a New Push Notification to Device(s)

This call will send a new push notification to one or several devices which secure IDs are specified as “recipients’.

METHOD URL
POST /push/notifications

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d "{"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"]}"

Parameters

Parameter Data Type Description
message string Json body of notification, example: {"a":"b","c":"d"}
notification_sid string Notification secure ID
recipients array List of devices secure IDs
ttl integer Time to live in seconds for notification
priority string Delivery priority for notification = ['very_low', 'low', 'normal', 'high', 'very_high']
partner_sid string Secure ID of the Partner which this message belongs to

Sample Response

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




Countries

The countries resource instance allows to retrieve extensive information for each country, like the country code in universally accepted formats, mobile country code, dialing prefix, etc. It helps to define which country the specified IP address belongs to.

Get Countries Matching the Specified Criteria

Shows the list of countries. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true,

METHOD URL
GET /countries

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/countries?filter=capital%20ne%20Kabul%20and%20dialing_prefix%20gt%201&order=common_name%20asc'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
common_name eq Italy
name like Italy and country_code ne USA
order string Specifies order of items in the response: asc, desc

Example:
common_name desc
country_code asc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"common_name": "Andorra",
"official_name": "Principality of Andorra",
"iso_3166_alpha_2": "AD",
"iso_3166_alpha_3": "AND",
"iso_3166_numeric": 20,
"domain": "ad",
"dialing_prefix": "376",
"region": "Europe",
"subregion": "Southern Europe",
"capital": "Andorra la Vella",
"mcc": "213"
}

Attributes

Attribute Data Type Description
common_name string Common name of the country
official_name string Official name of the country
iso_3166_alpha_2 string ISO 3166-1 alpha-2 code of this country
iso_3166_alpha_3 string ISO 3166-1 alpha-3 code of this country
iso_3166_numeric string ISO 3166-1 numeric code of this country
domain string The Internet domain of this country
dialing_prefix string Telephone code of this country
region string Region of this сountry
subregion string Sub region of this сountry
capital string The capital of this сountry
mcc integer Mobile country code

Get Country by ISO 3166-1 alpha-3 code

Shows the country which ISO 3166-1 alpha-3 code is specified.

METHOD URL
GET /countries/{country_code}

Sample URL


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

Parameters

Parameter Data Type Description
country_code req string ISO 3166-1 alpha-3 code of this Country
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response.

Sample Response

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

Attributes

Attribute Data Type Description
common_name string Common name of the country
official_name string Official name of the country
iso_3166_alpha_2 string ISO 3166-1 alpha-2 code of this country
iso_3166_alpha_3 string ISO 3166-1 alpha-3 code of this country
iso_3166_numeric string ISO 3166-1 numeric code of this country
domain string The Internet domain of this country
dialing_prefix string Telephone code of this country
region string Region of this country
subregion string Sub region of this country
capital string The capital of this country
mcc integer Mobile country code

Get Country by IP address

Shows the country which the specified IP address belongs to.

METHOD URL
GET /countries/ip/{ip_adress}

Sample URL


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

Parameters

Parameter Data Type Description
ip_address req string IPv4 address
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"iso_3166_alpha_2": "FR",
"common_name": "France"
}

Attributes

Attribute Data Type Description
iso_3166_alpha_2 opt string ISO 3166-1 alpha-2 code of this country
common_name opt string Common name of the country





Calls

Get CDRs (Call Detail Records) Matching the Specified Criteria

This call is used to retrieve detailed information about inbound and outbound calls that have been placed: date and time, originating and destination numbers, ip addresses of the calling numbers, direction, etc. If not filtered, the call will show all available CDRs. The number of displayed items will be limited by the limit/offset values only. If the number of items exceeds the limit value, the has_more in the response is set to true,

METHOD URL
GET /calls/cdrs

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/calls/cdrs?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
direction eq "outbound" and disconnect_originator eq "BRIDGE"
order string Specifies order of items in the response: asc, desc

Example:
duration desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "dr_sid": "71985ce1-9272-4a84-9404-5f2c686fb9d3",
  "version": 2,
  "type": "telecom",
  "direction": "outbound",
  "toll_free_call": false,
  "equipment_id": "ivs-10.1.10.67",
  "number_src": "+15167508701",
  "number_dst": "15162065040",
  "date_insert": "2016-04-26T00:55:02.000Z",
  "date_start": "2016-04-26T00:52:10.000Z",
  "date_talk": "2016-04-26T00:52:10.000Z",
  "date_stop": "2016-04-26T00:52:10.000Z",
  "owner_sid": "Lbid9-8UXvdoCHDiHYoEmm7raufEQWZJ",
  "other_sid": null,
  "price": "0.0000",
  "duration": 0,
  "duration_audio": 0,
  "duration_video": 0,
  "duration_data": 0,
  "disconnect_originator": "BRIDGE",
  "disconnect_cause": "58",
  "disconnect_reason": "Normal",
  "ip_src": "10.2.110.195",
  "ip_dst": "unknown",
  "sipcallid_src": "2d8ec7f3343b10b9090b73b86093ce22@10.2.110.202",
  "sipcallid_dst": null,
  "ref_id": "icid-value=434a1ebbba;icid-generated-at=10.1.10.67",
  "cluster_id": "copy-ow"
}

Attributes

Attribute Data Type Description
dr_sid opt string Secure ID of the record
version opt integer Version of the DR as it comes from the resource.
type opt string Possible values are : telecom, sms, conference, application
direction opt string inbound - incoming call or sms
outbound - outgoing call or sms
toll_free_call boolean Shows whether the call is toll free or not
equipment_id opt string String to identify equipment received from the resource.
number_src opt string Source number:
  • calling number - if the call is outbound
  • called number – if the call is inbound
number_dst opt string Destination number:
  • called number - if the call is outbound
  • calling number - if the call is inbound
date_insert opt string Date when the DR was inserted into the database
date_start opt string Date and time of the call start or sms creation
date_talk opt string Date and time of answer on the destination side
date_stop opt string Date and time when the call or sms were delivered.
owner_sid opt string Partner SID of responsible party (shall not be null). In the case of inbound direction should contain a partner for number_dst (we shall have number_dst in the system in this case)
other_sid opt string Partner SID of other side of the call. Can be null for outbound direction for call or SMS to number outside of our system.
price opt string Price for the DR.
duration opt integer Overall call duration in seconds ( date_stop - date_start);
duration_audio opt integer Date and time when the call or sms were delivered.
duration_video opt integer Video call duration in seconds; always 0 for SMS.
duration_data opt integer Data call duration in seconds (for example, Screen Sharing seconds); always 0 for SMS.
disconnect_originator opt string Origniator who drops the call; null for sms.
disconnect_cause opt string ISDN code of call termination.
disconnect_reason opt string Specific disconnect reason received from the resource.
ip_src opt string IP address of the source of call.
ip_dst opt string IP address of the destination of call.
sipcallid_src opt string Sip-call ID of the source of call.
ref_id opt string Internal ID of the call.
cluster_id opt string Cluster ID

Get CDR (Call Detail Record) by SID

This call will retrieve data for a particular CDR which secure ID is specified.

METHOD URL
GET /calls/cdrs/{dr_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/calls/call_drs/61287db3-4cab-442b-a0bc-db236bea83b2'

Parameters

Parameter Data Type Description
dr_sid req string Secure ID of the CDR
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "dr_sid": "61287db3-4cab-442b-a0bc-db236bea83b2",
  "version": 2,
  "type": "telecom",
  "direction": "inbound",
  "toll_free_call": false,
  "equipment_id": "ivs-12.7.192.27",
  "number_src": "7605692222",
  "number_dst": "17208209036",
  "date_insert": "2016-10-12T10:50:02.000Z",
  "date_start": "2016-10-12T10:47:26.000Z",
  "date_talk": "2016-10-12T10:47:32.000Z",
  "date_stop": "2016-10-12T10:47:32.000Z",
  "owner_sid": "rgrg95is-vPGB9DZxM9-m3geQgg8qIzw",
  "other_sid": "6bd4239b-e8e9-4d8d-a715-072810fb0ed5",
  "price": null,
  "duration": 6,
  "duration_audio": 0,
  "duration_video": 0,
  "duration_data": 0,
  "disconnect_originator": "DST",
  "disconnect_cause": "18",
  "disconnect_reason": "Normal",
  "ip_src": "12.7.193.87",
  "ip_dst": "10.2.111.72:5060",
  "sipcallid_src": "4ab77c516ee78a0f374faa25118e6760@12.7.193.81",
  "sipcallid_dst": null,
  "ref_id": "icid-value=1b15fe14be;icid-generated-at=12.7.192.27",
  "cluster_id": "ow-ivs"
}

Attributes

Attribute Data Type Description
dr_sid opt string Secure ID of the record/td>
version opt integer Version of the DR as it comes from the resource.
type opt string Possible values are : telecom, sms, conference
direction opt string 1 - incoming call or sms
2 - outgoing call or sms
Calculated on the basis of ordered DID,
toll_free_call opt boolean Shows whether the call is toll free or not
equipment_id opt string String to identify equipment received from the resource.
number_src opt string Source number. It is calling number in the case of outbound direction or called number in the case of inbound.
number_dst opt string Destination number. It is called number in the case of outbound direction or calling number in the case of inbound.
date_insert opt string Date when the DR was inserted into the database.
date_start opt string Date when the call was started, or sms created.
date_talk opt string Date and time of answer on the destination side.
date_stop opt string Date and time when the call or sms were delivered.
owner_sid opt string Partner SID of responsible party (shall not be null). In the case of inbound direction should contain a partner for number_dst (we shall have number_dst in the system in this case)
other_sid opt string Partner SID of other side of the call. Can be null for outbound direction for call or SMS to number outside of our system.
price opt string Price for the DR
duration opt integer Overall call duration in seconds ( date_stop - date_start);
duration_audio opt integer Date and time when the call or sms were delivered.
duration_video opt integer Video call duration in seconds; always 0 for SMS.
duration_data opt integer Data call duration in seconds (for example, Screen Sharing seconds); always 0 for SMS.
disconnect_originator opt string Origniator who drops the call; null for sms.
disconnect_cause opt string ISDN code of call termination.
disconnect_reason opt string Specific disconnect reason received from the resource.
ip_src opt string IP address of the source of call.
ip_dst opt string IP address of the destination of call.
sipcallid_src opt string Sip-call ID of the source of call.
ref_id opt string Internal ID of the call.
cluster_id opt string Cluster ID

Get Inbound Rates Matching the Specified Criteria

This specific API shows the list of inbound rates. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true. partner_sid is indicated, the call will return all rates for the currently logged in call initiator. To see the rates of other partners you need to specify their secure IDs.

METHOD URL
GET /calls/rates/inbound

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/calls/rates/inbound?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
prefix ne 15615
order string Specifies order of items in the response: asc, desc

Example:
price desc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
 {
    "prefix": "1587985",
    "price": "0.01",
    "country_code": "USA"
  }
}

Attributes

Attribute Data Type Description
country_code opt string ISO 3166-1 alpha-3 code of this Rate
prefix opt string Number prefix for this call rate (first digits of the phone number used for rate matching)
price opt string Price for the rate

Get Outbound Rates Matching the Specified Criteria

This specific API shows the list of outbound rates. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true. partner_sid is indicated, the call will return all rates for the currently logged in call initiator. To see the rates of other partners you need to specify their secure IDs.

METHOD URL
GET /calls/rates/outbound

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/calls/rates/outbound?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default is 10
filter string Filter the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
prefix eq 15615
order string Specifies order of items in the response: asc, desc

Example:
name desc
code asc

The default order is ascending.
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"offset": 0,
"limit": 10,
"total": 10,
"has_more": true,
"partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
"effective_date": "2015-10-01T00:00:00.000Z",
"active": "yes",
"items": [
 {
    "prefix": "1587985",
    "price": "0.01",
    "country_code": "USA"
  }
}

Attributes

Attribute Data Type Description
country_code opt string ISO 3166-1 alpha-3 code of this Rate
prefix opt string Number prefix for this call rate (first digits of the phone number used for rate matching)
price opt string Price for the rate


Access Control

Access Control List (ACL) allows Partners to control what calls are to be placed or received. Each ACL consists of the list of Access Control Rules. Each Access Control Rule represents a single check inside the ACL. It determines the scope of data to be checked in SIP calls, and serves as a re-usable building block for multiple ACLs.

Each Partner can see and use his own Access Control Rules and those that belong to his Parent Partner.
Each Partner can see and modify his own Access Control Rules only. Partner cannot modify or delete Access Control Rules that belong to his Parent Partner.

Get Effective ACLs for Calls

This call will return the list of effective ACLs for the Trunk Group which secure ID is provided. ACL’s Effective ACLs list is executed sequentially starting from the top parent down to the specified partner or Trunk Group i.e. first will be listed ACL’s of the Parent Partner(s).

METHOD URL
GET /accesscontrol/effective_acl/calls

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2//accesscontrol/effective_acl/calls?trunk_group_sid=6674fb5a-c62b-4224-a9ce-9e19bf583a64&direction=outbound'

Parameters

Parameter Data Type Description
partner_sid string Partner secure ID
trunk_group_sid string Trunk Group secure ID
direction string Direction for ACL. Possible values:
inbound, outbound, any
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "layer": 1,
  "effective_acls": [
      {
          "direction": "outbound",
          "voice_action_true": "reject403",
          "voice_action_false": null,
          "sms_action_true": null,
          "sms_action_false": null,
          "access_control_rules": [
              "68515527-f68f-48b0-a2c7-b7334270f8bd"
          ]
      },
      {
          "direction": "outbound",
          "voice_action_true": null,
          "voice_action_false": "reject403",
          "sms_action_true": null,
          "sms_action_false": null,
          "access_control_rules": [
              "6c8d7eea-234d-49e9-8e5c-6aff78601631"
          ]
      },
      {
          "direction": "outbound",
          "voice_action_true": "reject503",
          "voice_action_false": null,
          "sms_action_true": null,
          "sms_action_false": null,
          "access_control_rules": [
              "dafd993d-0e99-4af9-b8fc-436fb01b0bbe"
          ]
      }
  ]
}

Attributes

Attribute Data Type Description
direction string Direction for ACL. Possible values:
inbound, outbound, any
voice_action_true string Action to be executed for call if any of Access Control Rules is applied. Possible values:
accept, reject403, reject503
voice_action_false string Action to be executed for call if none of Access Control Rules is applied. Possible values:
accept, reject403, reject503
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs

Get Effective ACLs for SMS

This call will return the list of effective ACLs for the Partner which secure ID is provided. ACL’s Effective ACLs list is executed sequentially starting from the top parent down to the specified partner, i.e. first will be listed ACL’s of the Parent Partner(s).

METHOD URL
GET /sms/{partner_sid}/effective_acl

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/sms/6bd4239b-e8e9-4d8d-a715-072810fb0ed5/effective_acl'

Parameters

Parameter Data Type Description
partner_sid string Partner secure ID
direction string Direction for ACL. Possible values:
inbound, outbound, any
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "layer": 1,
  "effective_acls": [
      {
         "direction": "outbound",
         "voice_action_true": null,
         "voice_action_false": null,
          "sms_action_true": "reject",
          "sms_action_false": null,
          "access_control_rules": [
              "fff3bd99-dfca-4896-b722-3e8e95311653"
          ]
      }
  ]
}

Attributes

Attribute Data Type Description
direction string Direction for ACL. Possible values:
inbound, outbound, any
sms_action_true string Action to be executed for sms if any of Access Control Rules is applied. Possible values:
accept, reject
sms_action_false string Action to be executed for sms if none of Access Control Rules is applied. Possible values:
accept, reject
access_control_rules array List of Access Control Rule secure IDs

Get Access Control Rules Matching the Specified Criteria

This call returns the list of Access Control Rules that match the given criteria, and that belong to the currently logged in Partner and his Parent. Partner cannot see Access Control Rules created by his sub Partners.
The read_only field shows whether the Access Control Rule belongs to the currently logged in Partner (set to false) true),

METHOD URL
GET /accesscontrol/rules

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/accesscontrol/rules?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name like "test" and field ne “to”
order string Specifies order of items in the response: asc, desc

Example:
name desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "offset": 0,
  "limit": 10,
  "total": 6,
  "has_more": false,
  "pagination": {},
  "items": [
      {
          "rule_sid": "5fb06689-9e62-45f8-84f6-111c3aa8598c",
          "name": "av_2a",
          "read_only": false,
          "field": "to_did",
          "quantifier": "any",
          "operation": "exact",
          "entries": [
              "15167802332",
              "18004507571",
              "14507894565"
          ]
      }
  ]
}

Attributes

Attribute Data Type Description
rule_sid string Access Control Rule secure ID
name string Access Control Rule name
read_only boolean Shows whether Access Control Rule can be modified or not
field string Field to check in a SIP call
quantifier string What from 'items' shall be checked against 'field' = ['all', 'any', 'none']
operation string How to check. Possible values: prefix, exact, regexp, builtin
entries string List of entries to check with

Create a New Access Control Rule

This call will add a new Access Control Rule for the currently logged in Partner. The mandatory fields are field, quantifier, entries, operation. name will be set to N/A if not specified otherwise.

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

METHOD URL
POST /accesscontrol/rules

Sample URL


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

Parameters

Parameter Data Type Description
body req ... Access Control Rule object

Sample Response

 {
  "rule_sid": "75884526-d062-4325-ab9d-fda8002041ea",
  "name": "av_2a",
  "read_only": false,
  "field": "to_did",
  "quantifier": "any",
  "operation": "exact",
  "entries": [
      "15167802332"
  ]
}

Attributes

Attribute Data Type Description
rule_sid string Access Control Rule secure ID
name string Access Control Rule name
read_only boolean Shows whether Access Control Rule can be modified or not
field string Field to check in a SIP call
quantifier string What from 'items' shall be checked against 'field' = ['all', 'any', 'none']
operation string How to check. Possible values: prefix, exact, regexp, builtin
entries string List of entries to check

Remove Access Control Rule

This call will remove an existing Access Control Rule object which secure ID is specified. Note: You cannot delete Access Control Rules that belong to your Parent Partner (i. e. "ready_only":"true").

METHOD URL
DELETE /accesscontrol/rules/rule_sid

Sample URL


curl -X DELETE --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/accesscontrol/rules/68593dc6-2fbb-4dd4-8399-b6093dc94f3d'

Parameters

Parameter Data Type Description
body req ... Access Control Rule object

Get Access Control Rule by SID

This call will return information for a particular Access Control Rule which secure ID is specified. Each Partner can see his Access Control Rules and those that belong to his Parent.

METHOD URL
GET /accesscontrol/rules/{rule_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/accesscontol/rules/a3cbea4b-cd3c-4da0-b7f4-3083282e6b9d'

Parameters

Parameter Data Type Description
rule_sid string Access Control Rule secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

 {
  "rule_sid": "a3cbea4b-cd3c-4da0-b7f4-3083282e6b9d",
  "name": "N/A",
  "read_only": true,
  "field": "to_did",
  "quantifier ": "any",
  "operation": "prefix",
  "entries": []
}

Attributes

Attribute Data Type Description
rule_sid string Access Control Rule secure ID
name string Access Control Rule name
read_only boolean Shows whether Access Control Rule can be modified or not
field string Field to check in a SIP call
quantifier string What from 'items' shall be checked against 'field' = ['all', 'any', 'none']
operation string How to check. Possible values: prefix, exact, regexp, builtin
entries string List of entries to be checked

Patch Access Control Rule

This call will modify fields of a particular Access Control Rule which secure ID is specified.

METHOD URL
PATCH /accesscontrol/rules/{rule_sid}

Sample URL


curl -X PATCH --header 'Accept: application/json' -d '{"name":"av_2bb"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/accesscontrol/rules/604e57e1-74fa-49c4-99af-495ff050a9d0'

Parameters

Parameter Data Type Description
rule_sid string Access Control Rule secure ID
body ... Fields to be modified

Sample Response

{
  "rule_sid": "604e57e1-74fa-49c4-99af-495ff050a9d0",
  "name": "av_2bb",
  "read_only": false,
  "field": "to_did",
  "quantifier ": "any",
  "operation": "exact",
  "entries": [
      "18004507578",
      "14507894567",
      "15167802334"
  ]
}

Attributes

Attribute Data Type Description
rule_sid string Access Control Rule secure ID
name string Access Control Rule name
read_only boolean Shows whether Access Control Rule can be modified or not
field string Field to check in a SIP call
quantifier string What from 'items' shall be checked against 'field' = ['all', 'any', 'none']
operation string How to check. Possible values: prefix, exact, regexp, builtin
entries string List of entries to be checked

Update Access Control Rule

This call will update a particular Access Control Rule object which secure ID is specified.
Note: Partner can update Access Control Rules that belong to him only. (i. e. "read_only":"false").

METHOD URL
PUT /accesscontrol/rules/{rule_sid}

Sample URL


curl -X PUT --header 'Accept: application/json' -d '{"rule_sid": "e214f6ab-7184-425b-85a9-7991e598ae72", "name": "N/A", "read_only": false, "field": "to_did", "quantifier ": "any", "operation": "prefix", "entries": [“180012”]}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/accesscontrol/rules/e214f6ab-7184-425b-85a9-7991e598ae72'

Parameters

Parameter Data Type Description
rule_sid string Access Control Rule secure ID
body ... Fields to be modified

Sample Response

 {
  "rule_sid": "214f6ab-7184-425b-85a9-7991e598ae72",
  "name": "N/A",
  "read_only": false,
  "field": "to_did",
  "quantifier ": "any",
  "operation": "prefix",
  "entries": [
      "180012",
     ]
}

Attributes

Attribute Data Type Description
rule_sid string Access Control Rule secure ID
name string Access Control Rule name
read_only boolean Shows whether Access Control Rule can be modified or not
field string Field to check in a SIP call
quantifier string What from 'items' shall be checked against 'field'. Possible values:
  • all
  • any
  • none
operation string How to check. Possible values:
  • prefix
  • exact
  • regexp
  • builtin
entries string List of entries to be checked


Invoices

The invoices resource instance allows to retrieve detailed invoice reports for each partner. Whenever a new partner is added to the system, an open invoice is created for his account. One and only one open invoice can exist for each partner at the same time. When a partner rents a new DID, the corresponding invoice is created. Each invoice may have one of the following status value:

  • open - new opened invoice;
  • complete - charged invoice;
  • decline - invoice that belongs to partner without billing method on file or invoice that was declined by payment gateway;
  • pending - invoice that belong to partner with check billing method on file. Pending status shows that this invoice is waiting for check to be received;
  • error - billing module received critical error while processing this invoice. Such invoices must be processed manually.

Get Invoices Matching the Specified Criteria

Shows the list of invoices. If no filter is specified, the number of displayed items will be limited by the limit and offset values only. If the number of items exceeds the limit value, the has_more value in the response will be set to true, pagination field will suggest moving either to the next page or the previous one.


METHOD URL
GET /invoices

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/invoices?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.

Example:
name eq “PSTN-GW” and parent_sid ne 0
order string Specifies order of items in the response: asc, desc

Example:
name desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "invoice_sid": "88841e77-64a7-4080-8d0f-762674bce817",
  "partner_sid": "417f4b84-2529-4541-9ab5-ebdd714e643e",
  "status": "open",
  "paid": false,
  "amount": 0,
  "amount_due": 0,
  "amount_tax": 0,
  "date_created": "2016-07-26T07:44:28.000Z",
  "date_charge_expected": "2016-08-25T23:59:59.000Z",
  "date_charged": null,
  "date_billing_period_start": "2016-07-26T00:00:00.000Z",
  "date_billing_period_end": "2016-08-25T23:59:59.000Z",
  "invoice_items": [
    {
      "type": "did",
      "amount": 3,
      "usage": 3,
      "country_code": "USA",
      "date_created": "2016-07-26T07:52:21.000Z",
      "date_billing_period_start": "2016-07-26T00:00:00.000Z",
      "date_billing_period_end": "2016-08-25T23:59:59.000Z"
    }
  ],
  "pay_items": [],
  "tax_items": []
}

Attributes

Attribute Data Type Description
invoice_sid opt string Invoice secure ID
partner_sid opt string Secure ID of the Partner to whom this DID belongs
status opt string Invoice status. Possible values are:
  • open
  • charging
  • pending
  • declined
  • complete
  • uncollectable
  • error
paid opt boolean Possible values: true / false.
Shows whether the invoice has been paid or not
amount opt integer Amount of invoice items
amount_due opt integer Amount due to pay
date_created opt string Date when the invoice was created
date_charge_expected opt string Date when the invoice will be charged
date_charged opt string Partner address
items type string Invoice item status. Possible values:
  • telecom
  • sms
  • did
amount integer Amount of invoice items
usage integer Usage
date_created string Date when the invoice was created
date_billing_period_start string Date when the billing period begins
date_billing_period_end string Date when the billing period ends
country_code string DID country code
pay_items
status string Invoice payment status. Possible values:
  • declined
  • complete
  • error
type string Invoice payment type. Possible values:
  • credit_card
  • check
  • balance
  • refund_credit_card
  • refund_check
  • charge_back
amount integer Amount of payments
date_charged string date when the payment was made
gateway_order_id string Gateway order ID
check_number string Check number that was used for payment
billing_method type string Type of the billing method. Possible values:
  • american_express
  • visa
  • master_cad
  • discover_card
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number string Credit card number
cc_expiration string Credit card expiration date in MMyyyy format
cc_cid string Credit card CID
ec_account_number string Electronic check account number
ec_routing_number string Electronic check routing number
name string Customer name
address1 string Customer address
address2 string Customer address
city string Customer city
state string Customer state: two-letter abbreviation code
zip string Customer zip code
country_code string Customer country ISO 3166-1 alpha-3 code
phone string Customer phone number
tax_items type string Invoice tax type. Possible values:
  • 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
jurisdiction string Invoice tax jurisdiction. Possible values are:
  • federal
  • state
  • county
  • local
  • unincorporated
  • other
  • state_county_local
  • county_local
amount integer Amount of taxes

Get Invoice by SID

This call will retrieve data for a particular invoice which secure ID is specified. You may use include_fields / exclude_fields parameters to refine the response.

METHOD URL
GET /invoices/{invoice_sid}

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/invoices/3e0e0905-3ae1-4830-b4c7-91c08e9fd6e0'

Parameters

Parameter Data Type Description
invoice req string Partner secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

 {
"invoice_sid": "3e0e0905-3ae1-4830-b4c7-91c08e9fd6e0",
"partner_sid": "ce523e49-175d-482e-a202-c44d78f1ffac",
"status": "open",
"paid": false,
"amount": 0,
"amount_due": 0,
"date_created": "2016-04-12T08:12:31.000Z",
"date_charge_expected": "2016-05-12T23:59:59.000Z",
"date_charged": null,
"date_billing_period_start": "2016-04-12T00:00:00.000Z",
"date_billing_period_end": "2016-05-12T23:59:59.000Z",
"items": [],
"pay_items": [],
"tax_items": []
}

Attributes

Attribute Data Type Description
invoice_sid opt string Invoice secure ID
partner_sid opt string Secure ID of the Partner to whom this DID belongs
status opt string Invoice status. Possible values are:
  • open
  • charging
  • pending
  • declined
  • complete
  • uncollectable
  • error
paid opt boolean Possible values: true / false.
Shows whether the invoice has been paid or not
amount opt integer Amount of invoice items
amount_due opt integer Amount due to pay
date_created opt string Date when the invoice was created
date_charge_expected opt string Date when the invoice will be charged
date_charged opt string Partner address
items type string Invoice item status. Possible values:
  • telecom
  • sms
  • did
amount integer Amount of invoice items
usage integer Usage
date_created string Date when the invoice was created
date_billing_period_start string Date when the billing period begins
date_billing_period_end string Date when the billing period ends
country_code string DID country code
pay_items
status string Invoice payment status. Possible values:
  • declined
  • complete
  • error
type string Invoice payment type. Possible values:
  • credit_card
  • check
  • balance
  • refund_credit_card
  • refund_check
  • charge_back
amount integer Amount of payments
date_charged string date when the payment was made
gateway_order_id string Gateway order ID
check_number string Check number that was used for payment
billing_method type string Type of the billing method. Possible values:
  • american_express
  • visa
  • master_cad
  • discover_card
  • jcb
  • international_maestro
  • electronic_check
  • check
cc_number string Credit card number
cc_expiration string Credit card expiration date in MMyyyy format
cc_cid string Credit card CID
ec_account_number string Electronic check account number
ec_routing_number string Electronic check routing number
name string Customer name
address1 string Customer address
address2 string Customer address
city string Customer city
state string Customer state: two-letter abbreviation code
zip string Customer zip code
country_code string Customer country ISO 3166-1 alpha-3 code
phone string Customer phone number
tax_items type string Invoice tax type. Possible values:
  • 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
jurisdiction string Invoice tax jurisdiction. Possible values are:
  • federal
  • state
  • county
  • local
  • unincorporated
  • other
  • state_county_local
  • county_local
amount integer Amount of taxes

Get Invoice HTML Report by SID

This call will retrieve data for a particular invoice in html format. If the call succeeds, you will see the Download link. Clicking the link will download the generated report in html format.

METHOD URL
GET /invoices/{invoice_sid}.html

Sample URL


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

Parameters

Parameter Data Type Description
invoice_sid req string Invoice secure ID




Lookup

Get Details for Phone Number

Shows detailed information for the specified phone number.

METHOD URL
GET /lookup/dids/{phonenumber}

Sample URL


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

Parameters

Parameter Data Type Description
phonenumber string Phone number
include_fields integer Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from response
cnam string Whether or not show CNAM information. Possible values:
  • true
  • false
lrn string Whether or not show local routing number. Possble values:
  • true
  • false
carrier string Whether or not show carrier information. Possible values:
  • true
  • false

Sample Response

 {
  "phonenumber": "18004501575",
  "country_code": "USA",
  "in_country_format": "(800) 450-1575",
  "international_format": "+1 800-450-1575",
  "capabilities": null,
  "details": {
      "cnam": {
          "name": "TOLL FREE CALL",
          "type": null
      },
      "lrn": "8004501575",
      "carrier": {
          "type": null,
          "mcc": null,
          "mnc": null,
          "name": null
      }
  },
  "attributes": {}
}

Attributes

Attribute Data Type Description
phonenumber string Phone number
country_code string ISO 3166-1 alpha-3 code of the country
in_country_format string DID in national format
international_format string DID in international format
details cnam name string Caller name
type string Caller type
lrn string Local routing number
carrier type string Type of the DID ("landline")
mcc integer Mobile Country Code
mnc integer Mobile Network Code
name string Carrier name
attributes string Additional attributes



Verification

Verify Email by Token

Verifies Partner's email by the inserted token.

METHOD URL
POST /verification/email/check/{token}

Sample URL


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

Parameters

Parameter Data Type Description
token string Verification token

Sample Response

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

Attributes

Attribute Data Type Description
status string Status of this verification item = ['created', 'sent_email', 'verified']
to_address string Verified email address
base_url string URL of the page to be re-addresses to after email verification
email_template_sid string Email template secure ID

Send a New Verification Email

The call will send a new verification email to the specified email address.

METHOD URL
POST /verification/email/send

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"to_address": "email@email.com"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/verification/email/send'

Parameters

Parameter Data Type Description
token string Verification token

Sample Response

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

Attributes

Attribute Data Type Description
status string Email verification status
to_address string Verified email address
base_url string URL of the page to be re-addresses to after email verification
email_template_sid string Email template secure ID

Get Email Templates Matching the Specified Criteria

The call will return the list of existing email templates.

METHOD URL
GET /verification/email/templates

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] https://api.carrierx.com/core/v2/verification/email/templates?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Skip this amount of items in the response
limit integer Return no more than this amount of items. Should not exceed 1000
filter string Specify filter for the items in the response. Supported operations are (eq, ne, gt, ge, lt, le, like, ilike, in). Several filters can be combined together. Example: name eq Test
order string Specify order of items in the response. Example: name desc
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

{
"template_sid": "3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba",
"name": "Email Verification template",
"type": "email_address_verification",
"subject": "QA: CarrierX Email Verification",
"from_address": "noreply@carrierx.com",
"to_addresses": null,
"cc_addresses": "dmitry.zalozhnov@carrierx.com",
"bcc_addresses": null,
"html_body": "Dear Customer,




To confirm email please click following link:



${base_url}?verification=${uuid}",

Attributes

Attribute Data Type Description
template_sid string Template secude ID
types string Template type. Possible values: invoice, email_address_verification
subject string Email subject
from_address string Address showing the email sender
to_addresses string Addresses of the recipients
cc_addresses string Addresses of the recipients to be in CC
bcc_addresses string Addresses of the recipients to be in BCC
html_body string Email html body
text_body string Email text body

Get Email Template by SID

The call will return a single email template instance by the specified secure ID.

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

Sample URL


curl -X GET --header 'Accept: application/json' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/verification/email/templates/3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba'

Parameters

Parameter Data Type Description
template_sid string Template secure ID
include_fields string Comma separated list of fields that should be included in response
exclude_fields string Comma separated list of fields that should be excluded from response

Sample Response

{
"template_sid": "3e9e8c56-e1ee-4dcf-9e2b-abbd101139ba",
"name": "Email Verification template",
"type": "email_address_verification",
"subject": "CarrierX Email Verification",
"from_address": "noreply@carrierx.com",
"to_addresses": null,
"cc_addresses": "dmitry.zalozhnov@carrierx.com",
"bcc_addresses": null,
"html_body": "Dear Customer,




To confirm email please click following link:



${base_url}?verification=${uuid}",

Attributes

Attribute Data Type Description
template_sid string Template secude ID
types string Template type. Possible values: invoice, email_address_verification
subject string Email subject
from_address string Address showing the email sender
to_addresses string Addresses of the recipients
cc_addresses string Addresses of the recipients to be in CC
bcc_addresses string Addresses of the recipients to be in BCC
html_body string Email html body
text_body string Email text body



Storage

Storage provides a great possibility for CarrierX partners to upload and store files of all formats. CarrierX will keep that media until you issue an HTTP DELETE. For your convenience, files can be sorted into containers. Each container can be set up to store a specific amount of files and/or specific amount of uploaded data.

Get Containers Matching the Specified Criteria

The service will obtain the list of existing containers that are availale for files upload.

METHOD URL
GET /storage/containers

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/storage/containers?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.
order string Specifies order of items in the response: asc, desc

Example:
name desc

include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "name": "N/A",
  "unique": false,
  "container_sid": "eb7c771c-9540-41e7-ab42-91cbdcd39efd",
  "partner_sid": "2ffe5027-ccad-42b0-9578-e1e374d9a7ce",
  "parent_container_sid": null,
  "quota_files": 100,
  "quota_bytes": 1073741824,
  "durability_class": "unassigned",
  "integer_key_1": null,
  "integer_key_2": null,
  "string_key_1": null,
  "string_key_2": null,
  "total_files": 1,
  "total_bytes": 168993,
  "available_files_percent": 99,
  "available_bytes_percent": 99
}

Attributes

Attribute Data Type Description
container_sid string Container secure ID
name string Container name
partner_sid string Secure ID of the Partner which this container belongs to
parent_container_sid string Parent container secure ID. If set, and referenced file no longer exists, this container will be deleted as well
quota_files integer Maximum number of files that can be stored in container; shall be positive
durability_class string Secure ID of the Partner which this Container belongs to = ['unassigned']
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
total_files integer Maximum number of files that can be stored in container; shall be positive
total_bytes integer Maximum size that can be stored in container; shall be positive
available_bytes_percent string Maximum number of bytes that can be stored in container; shall be positive
unique boolean Default false. if true, will prevent any future containers from being created with the same set of keys

Create a New Container

This call will create a new container object. Note: there cannot be two containers with the same set of key/value.

METHOD URL
POST /storage/containers

Sample URL


curl -X POST --header "Accept: application/json" -u [your_user_name]:[your_password] --data-binary '{"unique": "false", "parent_container_sid": "", "quota_files":"", "quota_bytes":"", "integer_key_1":"", "integer_key_2":"", "string_key_1":"", "string_key_2":""}' 'https://api.carrierx.com/core/v2/storage/containers'

Parameters

Parameter Data Type Description
body object body Body of the container object to be created

Sample Response


{
"name": "N/A",
"unique": false,
"container_sid": "b2aa2a90-f589-4043-98be-2d33c640c080",
"partner_sid": "c9Ua99icuPdvDvv2kvlNaPzMLDXwuEYJ",
"parent_container_sid": null,
"quota_files": 100,
"quota_bytes": 1073741824,
"durability_class": "unassigned",
"integer_key_1": null,
"integer_key_2": null,
"string_key_1": "",
"string_key_2": "",
"total_files": 0,
"total_bytes": 0,
"available_files_percent": 100,
"available_bytes_percent": 100
}

Attributes


Attribute Data Type Description
container_sid string Container secure ID
name string Container name
partner_sid string Secure ID of the Partner which this container belongs to
parent_container_sid string Parent container secure ID. If set, and referenced file no longer exists, this container will be deleted as well
quota_files integer Maximum number of files that can be stored in container; shall be positive
durability_class string Secure ID of the Partner which this Container belongs to = ['unassigned']
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
total_files integer Maximum number of files that can be stored in container; shall be positive
total_bytes integer Maximum size that can be stored in container; shall be positive
available_bytes_percent string Maximum number of bytes that can be stored in container; shall be positive
unique boolean Default false. if true, will prevent any future containers from being created with the same set of keys

Remove Container

This call will remove a particular existing container which secure ID is specified.

METHOD URL
DELETE /storage/containers/{container_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/storage/containers/b2aa2a90-f589-4043-98be-2d33c640c080'

Get Containers by SID

The service will obtain the single container which secure ID is specified

METHOD URL
GET /storage/containers/{container_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/storage/containers/51971768-0ae4-4e24-a209-8187565d0d76'

Parameters


Parameter Data Type Description
container_sid string Container secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "name": "N/A",
  "unique": false,
  "container_sid": "51971768-0ae4-4e24-a209-8187565d0d76",
  "partner_sid": "2ffe5027-ccad-42b0-9578-e1e374d9a7ce",
  "parent_container_sid": null,
  "quota_files": 100,
  "quota_bytes": 1073741824,
  "durability_class": "unassigned",
  "integer_key_1": null,
  "integer_key_2": null,
  "string_key_1": null,
  "string_key_2": null,
  "total_files": 1,
  "total_bytes": 168993,
  "available_files_percent": 99,
  "available_bytes_percent": 99
}

Attributes


Attribute Data Type Description
container_sid string Container secure ID
name string Container name
partner_sid string Secure ID of the Partner which this container belongs to
parent_container_sid string Parent container secure ID. If set, and referenced file no longer exists, this container will be deleted as well
quota_files integer Maximum number of files that can be stored in container; shall be positive
durability_class string Secure ID of the Partner which this Container belongs to = ['unassigned']
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
total_files integer Maximum number of files that can be stored in container; shall be positive
total_bytes integer Maximum size that can be stored in container; shall be positive
available_bytes_percent string Maximum number of bytes that can be stored in container; shall be positive
unique boolean Default false. if true, will prevent any future containers from being created with the same set of keys

Patch Container

This call will modify fields of a particular container object which secure ID is specified. Note: only parameters specified in the call will be updated. The other will preserve their current value.

METHOD URL
PATCH /storage/containers/{container_sid}

Sample URL


curl -X PATCH --header "Accept: application/json"  -d "{"name":"av_2bb"}" -u [your_user_name]:[your_password] '{"quota_files": "6", "quota_bytes": "7894561", "integer_key_1": "1", "integer_key_2": "2", "string_key_1": "value1", "string_key_2": "value2"}' 'https://api.carrierx.com/core/v2/storage/containers/5d42b396-e6e6-4b47-8de9-0cd5e0813a37'

Parameters


Parameter Data Type Description
container_sid string Container secure ID
body object body Fields to be modified

Sample Response 
{
  "name": "N/A",
  "unique": false,
  "container_sid": "5d42b396-e6e6-4b47-8de9-0cd5e0813a37",
  "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",
  "parent_container_sid": null,
  "quota_files": 6,
  "quota_bytes": 7894561,
  "durability_class": "unassigned",
  "integer_key_1": 1,
  "integer_key_2": 2,
  "string_key_1": "value1",
  "string_key_2": "value2",
  "total_files": 4,
  "total_bytes": 6326073,
  "available_files_percent": 96,
  "available_bytes_percent": 99
}


Attributes


Attribute Data Type Description
container_sid string Container secure ID
name string Container name
partner_sid string Secure ID of the Partner which this container belongs to
parent_container_sid string Parent container secure ID. If set, and referenced file no longer exists, this container will be deleted as well
quota_files integer Maximum number of files that can be stored in container; shall be positive
durability_class string Secure ID of the Partner which this Container belongs to = ['unassigned']
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
total_files integer Maximum number of files that can be stored in container; shall be positive
total_bytes integer Maximum size that can be stored in container; shall be positive
available_bytes_percent string Maximum number of bytes that can be stored in container; shall be positive
unique boolean Default false. if true, will prevent any future containers from being created with the same set of keys

Update Container

This call will update a particular container object which secure ID is specified.

METHOD URL
PUT /storage/containers/{container_sid}

Sample URL


curl -X PUT --header "Accept: application/json"  --data-binary '{ "name": "N/A", "unique": false, "container_sid": "5d42b396-e6e6-4b47-8de9-0cd5e0813a37", "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99", "parent_container_sid": null, "quota_files": 6, "quota_bytes": 7894561, "durability_class": "unassigned", "integer_key_1": 1, "integer_key_2": 2, "string_key_1": "value1", "string_key_2": "value2", "total_files": 4, "total_bytes": 6326073, "available_files_percent": 96, "available_bytes_percent": 99 }' -u : 'https://api.carrierx.com/core/v2/storage/containers/5d42b396-e6e6-4b47-8de9-0cd5e0813a37'

Parameters


Parameter Data Type Description
container_sid string Container secure ID
body object body Fields to be modified

Sample Response

  {
    "name": "N/A",
    "unique": false,
    "container_sid": "5d42b396-e6e6-4b47-8de9-0cd5e0813a37",
    "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",
    "parent_container_sid": null,
    "quota_files": 6,
    "quota_bytes": 7894561,
    "durability_class": "unassigned",
    "integer_key_1": 1,
    "integer_key_2": 2,
    "string_key_1": "value1",
    "string_key_2": "value2",
    "total_files": 4,
    "total_bytes": 6326073,
    "available_files_percent": 96,
    "available_bytes_percent": 99
  }

Attributes

Attribute Data Type Description
container_sid string Container secure ID
name string Container name
partner_sid string Secure ID of the Partner which this container belongs to
parent_container_sid string Parent container secure ID. If set, and referenced file no longer exists, this container will be deleted as well
quota_files integer Maximum number of files that can be stored in container; shall be positive
durability_class string Secure ID of the Partner which this Container belongs to = ['unassigned']
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
total_files integer Maximum number of files that can be stored in container; shall be positive
total_bytes integer Maximum size that can be stored in container; shall be positive
available_bytes_percent string Maximum number of bytes that can be stored in container; shall be positive
unique boolean Default false. if true, will prevent any future containers from being created with the same set of keys

Get Files Matching the Specified Criteria

The service will obtain the list of existing containers that are availale for files upload.

METHOD URL
GET /storage/files

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/storage/files?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.
order string Specifies order of items in the response: asc, desc
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "file_sid": "b051eb16-e4b6-4659-8e05-dc6dd755be80",
  "partner_sid": "66e6834a-4457-4222-90b4-2998e99d3141",
  "container_sid": "00a6dde9-2100-4815-acfe-950df724ef1b",
  "parent_file_sid": null,
  "name": "test.bin",
  "type": "file",
  "unique": false,
  "file_bytes": 2430663,
  "file_access_name": "b051eb16-e4b6-4659-8e05-dc6dd755be80",
  "publish": "file_sid",
  "publish_uri": "http://storage.int/f/b051eb16-e4b6-4659-8e05-dc6dd755be80",
  "integer_key_1": null,
  "integer_key_2": null,
  "string_key_1": null,
  "string_key_2": null,
  "lifecycle_ttl": -1,
  "lifecycle_action": null,
  "date_modified": "2017-07-31T12:44:03.000Z",
  "desired_format": null,
  "mime_type": "image/jpeg",
  "content_format": null,
  "content_duration": null,
  "content_transcoding_progress": null
}

Attributes

Attribute Data Type Description
file_bytes integer File size
date_modified string Date when the last update of the file took place
content_format string Format of the uploaded file
content_duration integer Duration of the file
content_transcoding_progress string Progress of the content transcoding
file_sid string File secure ID
name string File name
partner_sid string Secure ID of the Partner the file belongs to.
file_access_name string Path to the file within container. Defaults to file secure ID with extension if possible
publish_uri string Web accessible URI the file can be retrieved at. Only applicable if 'publish' set to true
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
lifecycle_ttl integer After specified number of seconds lifecycle_action will be triggered; -1 means eternity
lifecycle_action string Action to be triggered after lifecycle_ttl = ['delete']
desired_format string Desired format for audio and video file = ['mp3']
mime_type string Content type of the file
container_sid string Secure ID of the Container which this File belongs to
type string Type of the file (add extended specific functionality). Default is 'file' = ['file', 'audio', 'video', 'conference']
publish string ‘no': do not serve via public http. 'file_access_name': serve via http using the file_access_name field as path. 'file_sid': serve via http using the file_sid field as path = ['no', 'file_access_name', 'file_sid']
publish string Parent file secure ID. If set, and referenced file no longer exists, this file will be deleted as well

Upload a New File

This call will upload a new file to the storage to the specified container. Note: there can’t be two uploaded files with the same set of key/value if the ‘unique’ attribute is set to ‘true’.

METHOD URL
POST /storage/files

Sample URL


curl -X POST --header "Accept: application/json" -u [your_user_name]:[your_password] --data-binary '{"name":"File Name","type":"file","container_sid":"1645fb8e-b617-4507-b201-af4736622306","unique": "false","parent_file_sid": "","publish":"file_sid","lifecycle_ttl":-1,"lifecycle_action":null,"integer_key_1":"1","integer_key_2":"2","string_key_1":"string1","string_key_2":"string2"}' 'https://api.carrierx.com/core/v2/storage/files’

Parameters

Parameter Data Type Description
body object body Body of the file object to be uploaded

Sample Response

{
  "file_sid": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
  "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",
  "container_sid": "1645fb8e-b617-4507-b201-af4736622306",
  "parent_file_sid": null,
  "name": "File Name",
  "type": "file",
  "unique": false,
  "file_bytes": 2361592,
  "file_access_name": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b.JPG",
  "publish": "file_sid",
  "publish_uri": "http://storage.int/f/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
  "integer_key_1": 1,
  "integer_key_2": 2,
  "string_key_1": "string1",
  "string_key_2": "string2",
  "lifecycle_ttl": -1,
  "lifecycle_action": null,
  "date_modified": "2017-08-03T12:06:56.091Z",
  "desired_format": null,
  "mime_type": "image/jpeg",
  "content_format": null,
  "content_duration": null,
  "content_transcoding_progress": null
}

Attributes

Attribute Data Type Description
file_bytes integer File size
date_modified string Date when the last update of the file took place
content_format string Format of the uploaded file
content_duration integer Duration of the file
content_transcoding_progress string Progress of the content transcoding
file_sid string File secure ID
name string File name
partner_sid string Secure ID of the Partner the file belongs to.
file_access_name string Path to the file within container. Defaults to file secure ID with extension if possible
publish_uri string Web accessible URI the file can be retrieved at. Only applicable if 'publish' set to true
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
lifecycle_ttl integer After specified number of seconds lifecycle_action will be triggered; -1 means eternity
lifecycle_action string Action to be triggered after lifecycle_ttl = ['delete']
desired_format string Desired format for audio and video file = ['mp3']
mime_type string Content type of the file
container_sid string Secure ID of the Container which this File belongs to
type string Type of the file (add extended specific functionality). Default is 'file' = ['file', 'audio', 'video', 'conference']
publish string ‘no': do not serve via public http. 'file_access_name': serve via http using the file_access_name field as path. 'file_sid': serve via http using the file_sid field as path = ['no', 'file_access_name', 'file_sid']
publish string Parent file secure ID. If set, and referenced file no longer exists, this file will be deleted as well

Remove File

This call will remove a particular uploaded file which secure ID is specified.

METHOD URL
DELETE /storage/{file_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://qa-api.carrierx.com/core/v2/storage/files/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b'

Get File by SID

This call fetch the particular file which secure ID is defined.

METHOD URL
GET /storage/files/{file_sid}

Sample URL


curl -X PATCH --header "Accept: application/json"  -u [your_user_name]:[your_password] '{"name”: “New File Name”}' 'https://api.carrierx.com/core/v2/storage/files/0bbc2a22-84b5-4322-a420-f8232ea7cb0e'

Parameters

Parameter Data Type Description
file_sid string File secure ID
include_fields string Comma separated list of fields that should be included in the response.
exclude_fields string Comma separated list of fields that should be excluded from response.

Sample Response

{
  "file_sid": "0bbc2a22-84b5-4322-a420-f8232ea7cb0e",
  "partner_sid": "c730bd36-0c8c-4df1-9bec-cdb5b81f149a",
  "container_sid": "51971768-0ae4-4e24-a209-8187565d0d76",
  "parent_file_sid": null,
  "name": "15162065613-15187779817.wav",
  "type": "file",
  "unique": false,
  "file_bytes": 69262,
  "file_access_name": "0bbc2a22-84b5-4322-a420-f8232ea7cb0e.wav",
  "publish": "file_sid",
  "publish_uri": "http://qa-storage-fcc4d.int/f/0bbc2a22-84b5-4322-a420-f8232ea7cb0e",
  "integer_key_1": null,
  "integer_key_2": null,
  "string_key_1": null,
  "string_key_2": null,
  "lifecycle_ttl": -1,
  "lifecycle_action": null,
  "date_modified": "2017-08-18T09:40:08.000Z",
  "desired_format": null,
  "mime_type": "audio/x-wav",
  "content_format": null,
  "content_duration": null,
  "content_transcoding_progress": null
}

Attributes


Attribute Data Type Description
file_bytes integer File size
date_modified string Date when the last update of the file took place
content_format string Format of the uploaded file
content_duration integer Duration of the file
content_transcoding_progress string Progress of the content transcoding
file_sid string File secure ID
name string File name
partner_sid string Secure ID of the Partner the file belongs to.
file_access_name string Path to the file within container. Defaults to file secure ID with extension if possible
publish_uri string Web accessible URI the file can be retrieved at. Only applicable if 'publish' set to true
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
lifecycle_ttl integer After specified number of seconds lifecycle_action will be triggered; -1 means eternity
lifecycle_action string Action to be triggered after lifecycle_ttl = ['delete']
desired_format string Desired format for audio and video file = ['mp3']
mime_type string Content type of the file
container_sid string Secure ID of the Container which this File belongs to
type string Type of the file (add extended specific functionality). Default is 'file' = ['file', 'audio', 'video', 'conference']
publish string ‘no': do not serve via public http. 'file_access_name': serve via http using the file_access_name field as path. 'file_sid': serve via http using the file_sid field as path = ['no', 'file_access_name', 'file_sid']
publish string Parent file secure ID. If set, and referenced file no longer exists, this file will be deleted as well

Patch File

This call will modify attributes of a particular file object which secure ID is specified. Note: only parameters specified in the call will be updated. The other will preserve their current value.

METHOD URL
PATCH /storage/files/{file_sid}

Sample URL


curl -X PATCH --header "Accept: application/json"  -d "{"name":"av_2bb"}" -u [your_user_name]:[your_password] '{"name”: “New File Name”}' ''https://api.carrierx.com/core/v2/storage/files/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b'

Parameters

Parameter Data Type Description
file_sid string File secure ID
body object body Fields to be modified
file File for upload

Sample Response

{
  "file_sid": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
  "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",
  "container_sid": "1645fb8e-b617-4507-b201-af4736622306",
  "parent_file_sid": null,
  "name": "File Name",
  "type": "file",
  "unique": false,
  "file_bytes": 2697014,
  "file_access_name": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b.JPG",
  "publish": "file_sid",
  "publish_uri": "http://qa-storage-fcc4d.int/f/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
  "integer_key_1": 1,
  "integer_key_2": 2,
  "string_key_1": "string1",
  "string_key_2": "string2",
  "lifecycle_ttl": -1,
  "lifecycle_action": null,
  "date_modified": "2017-08-03T13:08:49.189Z",
  "desired_format": null,
  "mime_type": "image/jpeg",
  "content_format": null,
  "content_duration": null,
  "content_transcoding_progress": null
}

Attributes


Attribute Data Type Description
file_bytes integer File size
date_modified string Date when the last update of the file took place
content_format string Format of the uploaded file
content_duration integer Duration of the file
content_transcoding_progress string Progress of the content transcoding
file_sid string File secure ID
name string File name
partner_sid string Secure ID of the Partner the file belongs to.
file_access_name string Path to the file within container. Defaults to file secure ID with extension if possible
publish_uri string Web accessible URI the file can be retrieved at. Only applicable if 'publish' set to true
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
lifecycle_ttl integer After specified number of seconds lifecycle_action will be triggered; -1 means eternity
lifecycle_action string Action to be triggered after lifecycle_ttl = ['delete']
desired_format string Desired format for audio and video file = ['mp3']
mime_type string Content type of the file
container_sid string Secure ID of the Container which this File belongs to
type string Type of the file (add extended specific functionality). Default is 'file' = ['file', 'audio', 'video', 'conference']
publish string ‘no': do not serve via public http. 'file_access_name': serve via http using the file_access_name field as path. 'file_sid': serve via http using the file_sid field as path = ['no', 'file_access_name', 'file_sid']
publish string Parent file secure ID. If set, and referenced file no longer exists, this file will be deleted as well

Update File

This call will update a particular file which secure ID is specified.

METHOD URL
PUT /storage/files/{file_sid}

Sample URL


curl -X PUT --header "Accept: application/json"  --data-binary '{     "file_sid": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",     "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",     "container_sid": "1645fb8e-b617-4507-b201-af4736622306",     "parent_file_sid": null,     "name": "File Name",     "type": "file",     "unique": false,     "file_bytes": 2361592,     "file_access_name": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b.JPG",     "publish": "file_sid",    "publish_uri": "http://storage-fcc4d.int/f/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",     "integer_key_1": 1,     "integer_key_2": 2,     "string_key_1": "string1",     "string_key_2": "string2",     "lifecycle_ttl": -1,     "lifecycle_action": null,     "date_modified": "2017-08-03T12:06:56.091Z",     "desired_format": null,     "mime_type": "image/jpeg",     "content_format": null,     "content_duration": null,     "content_transcoding_progress": null }' -u: 'https://api.carrierx.com/core/v2/storage/files/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b'

Parameters

Parameter Data Type Description
file_sid string File secure ID
body Fields to be modified
file File for uploading

Sample Response

  {
    "file_sid": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
    "partner_sid": "57b384b0-6d84-4e9f-8b31-16cccf9e8c99",
    "container_sid": "1645fb8e-b617-4507-b201-af4736622306",
    "parent_file_sid": null,
    "name": "File Name",
    "type": "file",
    "unique": false,
    "file_bytes": 2697014,
    "file_access_name": "2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b.JPG",
    "publish": "file_sid",
    "publish_uri": "http://storage.int/f/2e3b1ecc-6f3e-4be6-a7aa-2f24a9c3e20b",
    "integer_key_1": 1,
    "integer_key_2": 2,
    "string_key_1": "string1",
    "string_key_2": "string2",
    "lifecycle_ttl": -1,
    "lifecycle_action": null,
    "date_modified": "2017-08-03T13:08:49.189Z",
    "desired_format": null,
    "mime_type": "image/jpeg",
    "content_format": null,
    "content_duration": null,
    "content_transcoding_progress": null
  }

Attributes

Attribute Data Type Description
file_bytes integer File size
date_modified string Date when the last update of the file took place
content_format string Format of the uploaded file
content_duration integer Duration of the file
content_transcoding_progress string Progress of the content transcoding
file_sid string File secure ID
name string File name
partner_sid string Secure ID of the Partner the file belongs to.
file_access_name string Path to the file within container. Defaults to file secure ID with extension if possible
publish_uri string Web accessible URI the file can be retrieved at. Only applicable if 'publish' set to true
integer_key_1 integer User defined integer key
integer_key_2 integer User defined integer key
string_key_1 string User defined string key
string_key_2 string User defined string key
lifecycle_ttl integer After specified number of seconds lifecycle_action will be triggered; -1 means eternity
lifecycle_action string Action to be triggered after lifecycle_ttl = ['delete']
desired_format string Desired format for audio and video file = ['mp3']
mime_type string Content type of the file
container_sid string Secure ID of the Container which this File belongs to
type string Type of the file (add extended specific functionality). Default is 'file' = ['file', 'audio', 'video', 'conference']
publish string ‘no': do not serve via public http. 'file_access_name': serve via http using the file_access_name field as path. 'file_sid': serve via http using the file_sid field as path = ['no', 'file_access_name', 'file_sid']
publish string Parent file secure ID. If set, and referenced file no longer exists, this file will be deleted as well





Shortener

Get Domains Matching the Specified Criteria

The service will obtain the list of existing domains for the currently logged in partner.

METHOD URL
GET /shortener/domains

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] https://api.carrierx.com/core/v2/shortener/domains?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "domain_sid": "210a645d-bb11-4945-bbda-9ee784cd8ade",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "domain_name": "mydomain1.com",
  "scope": "public",
  "minimum_length": 6,
  "not_found_page": null,
  "not_found_mode": "redirect_temporary",
  "not_found_status_code": null,
  "expired_page": null,
  "expired_mode": "redirect_temporary",
  "expired_status_code": null,
  "secure": false,
  "suffix_pattern": null
}

Attributes

Attribute Data Type Description
domain_sid string Domain secure ID
partner_sid string Secure ID of the Partner which this domain belongs to
domain_name string Unique domain name
scope string Field controls who may create a link using this domain_sid = ['self', 'children', '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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
not_found_status_code integer Status code to be returned if not_found_mode is "proxy". 2xx, 4xx, 5xx are valid
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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
expired_status_code integer Status code to be returned if expired_mode is "proxy". 2xx, 4xx, 5xx are valid
secure boolean Whether links returned should be prefixed with https. Default is false.
suffix_pattern string regexp of allowable suffixes the http server will allow for partial links. "" (default) will not allow a suffix. ".(mp3|pts|asn)" would allow one of these filename extensions only

Create a New Domain

This call will create a new domain object.

METHOD URL
POST /shortener/domains

Sample URL


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

Parameters

Parameter Data Type Description
body object body Body of the domain object to be created

Sample Response

{
  "domain_sid": "2694fba5-499c-4e14-b895-90af07dad674",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "domain_name": "newdomain.com",
  "scope": "public",
  "minimum_length": 6,
  "not_found_page": null,
  "not_found_mode": "redirect_temporary",
  "not_found_status_code": null,
  "expired_page": null,
  "expired_mode": "redirect_temporary",
  "expired_status_code": null,
  "secure": false,
  "suffix_pattern": null
}

Attributes

Attribute Data Type Description
domain_sid string Domain secure ID
partner_sid string Secure ID of the Partner which this domain belongs to
domain_name string Unique domain name
scope string Field controls who may create a link using this domain_sid = ['self', 'children', '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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
not_found_status_code integer Status code to be returned if not_found_mode is "proxy". 2xx, 4xx, 5xx are valid
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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
expired_status_code integer Status code to be returned if expired_mode is "proxy". 2xx, 4xx, 5xx are valid
secure boolean Whether links returned should be prefixed with https. Default is false.
suffix_pattern string regexp of allowable suffixes the http server will allow for partial links. "" (default) will not allow a suffix. ".(mp3|pts|asn)" would allow one of these filename extensions only

Remove Domain

This call will remove a particular existing domain which secure ID is specified.

METHOD URL
DELETE /shortener/domains/{domain_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/shortener/domains/6b4d3b00-aa96-470c-8139-500a05d683b9'

Parameters

Parameter Data Type Description
domain_sid string Secure ID of the domain which is meant to be deleted

Get Domain by SID

This call will fetch information for the specified domain object

METHOD URL
GET /shortener/domains/{domain_sid}

Sample URL


curl -X GET --header "Accept: application/json"  -d "{"name":"av_2bb"}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/shortener/domains/3ccfa22e-6927-4856-a088-0c4df348f26e'

Parameters

Parameter Data Type Description
domain_sid string Domain secure ID
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "domain_name": "mydomain3.com",
  "scope": "public",
  "minimum_length": 6,
  "not_found_page": null,
  "not_found_mode": "redirect_temporary",
  "not_found_status_code": null,
  "expired_page": null,
  "expired_mode": "redirect_temporary",
  "expired_status_code": null,
  "secure": false,
  "suffix_pattern": null
}

Attributes

Attribute Data Type Description
domain_sid string Domain secure ID
partner_sid string Secure ID of the Partner which this domain belongs to
domain_name string Unique domain name
scope string Field controls who may create a link using this domain_sid = ['self', 'children', '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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
not_found_status_code integer Status code to be returned if not_found_mode is "proxy". 2xx, 4xx, 5xx are valid
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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
expired_status_code integer Status code to be returned if expired_mode is "proxy". 2xx, 4xx, 5xx are valid
secure boolean Whether links returned should be prefixed with https. Default is false.
suffix_pattern string regexp of allowable suffixes the http server will allow for partial links. "" (default) will not allow a suffix. ".(mp3|pts|asn)" would allow one of these filename extensions only

Patch Domain

This call will modify fields of a particular domain object which secure ID is specified. Note: only parameters specified in the call will be updated. The other will preserve their current value.

METHOD URL
PATCH /shortener/domains/{domain_sid}

Sample URL


curl -X PATCH --header "Accept: application/json"  --data-binary '{"domain_name":"newdomainname.com"}' -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/shortener/domains/3ccfa22e-6927-4856-a088-0c4df348f26e'

Parameters

Parameter Data Type Description
domain_sid string Domain secure ID
body object body Fields to be modified

Sample Response 
{
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "domain_name": "mydomain3.com",
  "scope": "public",
  "minimum_length": 6,
  "not_found_page": null,
  "not_found_mode": "redirect_temporary",
  "not_found_status_code": null,
  "expired_page": null,
  "expired_mode": "redirect_temporary",
  "expired_status_code": null,
  "secure": false,
  "suffix_pattern": null
}


Attributes

Attribute Data Type Description
domain_sid string Domain secure ID
partner_sid string Secure ID of the Partner which this domain belongs to
domain_name string Unique domain name
scope string Field controls who may create a link using this domain_sid = ['self', 'children', '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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
not_found_status_code integer Status code to be returned if not_found_mode is "proxy". 2xx, 4xx, 5xx are valid
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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
expired_status_code integer Status code to be returned if expired_mode is "proxy". 2xx, 4xx, 5xx are valid
secure boolean Whether links returned should be prefixed with https. Default is false.
suffix_pattern string regexp of allowable suffixes the http server will allow for partial links. "" (default) will not allow a suffix. ".(mp3|pts|asn)" would allow one of these filename extensions only

Update Domain

This call will update a particular domain object which secure ID is specified.

METHOD URL
PUT /shortener/domains/{domain_sid}

Sample URL


curl -X PUT --header "Accept: application/json"  --data-binary '{ "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e", "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x", "domain_name": "mydomain3.com", "scope": "public", "minimum_length": 6, "not_found_page": null, "not_found_mode": "redirect_temporary", "not_found_status_code": null, "expired_page": null, "expired_mode": "redirect_temporary", "expired_status_code": null, "secure": false, "suffix_pattern": null }'  -u : 'https://api.carrierx.com/core/v2/shortener/domains/3ccfa22e-6927-4856-a088-0c4df348f26e''

Parameters

Parameter Data Type Description
domain_sid string Domain secure ID
body object body Fields to be modified

Sample Response

  {
    "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "domain_name": "mydomain3.com",
    "scope": "public",
    "minimum_length": 6,
    "not_found_page": null,
    "not_found_mode": "redirect_temporary",
    "not_found_status_code": null,
    "expired_page": null,
    "expired_mode": "redirect_temporary",
    "expired_status_code": null,
    "secure": false,
    "suffix_pattern": null
  }

Attributes

Attribute Data Type Description
domain_sid string Domain secure ID
partner_sid string Secure ID of the Partner which this domain belongs to
domain_name string Unique domain name
scope string Field controls who may create a link using this domain_sid = ['self', 'children', '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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
not_found_status_code integer Status code to be returned if not_found_mode is "proxy". 2xx, 4xx, 5xx are valid
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. Default "redirect" uses 302 (temporary redirect) = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
expired_status_code integer Status code to be returned if expired_mode is "proxy". 2xx, 4xx, 5xx are valid
secure boolean Whether links returned should be prefixed with https. Default is false.
suffix_pattern string regexp of allowable suffixes the http server will allow for partial links. "" (default) will not allow a suffix. ".(mp3|pts|asn)" would allow one of these filename extensions only

Get Links Matching the Specified Criteria

The service will obtain the list of existing links for the currently logged in partner.

METHOD URL
GET /shortener/links

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/shortener/links?offset=0&limit=10'

Parameters

Parameter Data Type Description
offset integer Amount of items to be skipped in the response. Default value is 0
limit integer Number of items to be shown in the response. The value should not exceed 1000. Default value is 10
filter string Specify the filter for the items in the response.
Supported operations are eq, ne, gt, ge, lt, le, like, ln
Multiple filters can be combined together.
order string Specifies order of items in the response: asc, desc

Example:
name desc

The default order is ascending
include_fields string Comma separated list of fields that should be included in the response
exclude_fields string Comma separated list of fields that should be excluded from the response

Sample Response

{
  "link_sid": "67dc1b22-de52-4c89-895c-61d8388cd5e5",
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "date_created": "2017-12-08T13:07:55.776Z",
  "date_accessed": null,
  "url": "http://mydomain3.com/YYWeM0",
  "destination_url": "http://destinationurl.com",
  "short_name": "YYWeM0",
  "mode": "redirect_temporary",
  "maximum_ttl": -1,
  "hits": 0
}

Attributes

Attribute Data Type Description
link_sid string Link secure ID
domain_sid string Domain secure ID
partner_sid string Partner secure ID
date_created string Date when the link was created
date_accessed string Date when the link was accessed
url string URL to get an access to destination_url, generated automatically
destination_url string Site where user will be sent to
short_name string Short portion of the url. If omit, it will be automatically generated. Unique with domain_sid
mode string May be "proxy" or "redirect" (301). Defaults to "redirect" = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
maximum_ttl integer Link lifetime in seconds, -1 means eternity
hits integer Link hits quantity

Create a New Link

This call will create a new link object.

METHOD URL
POST /shortener/links

Sample URL


curl -X POST --header "Accept: application/json" -u [your_user_name]:[your_password] --data-binary '{"domain_sid":"3ccfa22e-6927-4856-a088-0c4df348f26e", "destination_url":"http://destinationurl.com", "maximum_ttl":"-1"}' 'https://api.carrierx.com/core/v2/shortener/links'

Parameters

Parameter Data Type Description
body object body Body of the link object to be created

Sample Response

{
  "link_sid": "ef3a533d-51d0-4777-a4b5-bc97ab0825d7",
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "date_created": "2017-12-15T13:03:02.022Z",
  "date_accessed": null,
  "url": "http://mydomain3.com/BEgqdK",
  "destination_url": "http://destinationurl.com",
  "short_name": "BEgqdK",
  "mode": "redirect_temporary",
  "maximum_ttl": -1,
  "hits": 0
}

Attributes

Attribute Data Type Description
link_sid string Link secure ID
domain_sid string Domain secure ID
partner_sid string Partner secure ID
date_created string Date when the link was created
date_accessed string Date when the link was accessed
url string URL to get an access to destination_url, generated automatically
destination_url string Site where user will be sent to
short_name string Short portion of the url. If omit, it will be automatically generated. Unique with domain_sid
mode string May be "proxy" or "redirect" (301). Defaults to "redirect" = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
maximum_ttl integer Link lifetime in seconds, -1 means eternity
hits integer Link hits quantity

Remove Link

This call will remove a particular link which secure ID is specified.

METHOD URL
DELETE /shortener/links/{link_sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] ‘https://api.carrierx.com/core/v2/shortener/links/ef3a533d-51d0-4777-a4b5-bc97ab0825d7'

Parameters

Parameter Data Type Description
link_sid string Secure ID of the link which is meant to be deleted

Get Link by SID

This call will fetch information for the specified link object

METHOD URL
GET /shortener/links/{link_sid}

Sample URL


curl -X GET --header "Accept: application/json"  -d "{"name":"av_2bb"}" -u [your_user_name]:[your_password] 'https://api.carrierx.com/core/v2/shortener/links/f144a51a-20f5-4d2e-8864-0d889f212eda'

Parameters

Parameter Data Type Description
link_sid string Link secure ID
include_fields string Comma separated list of fields that should be included in the response.
exclude_fields string Comma separated list of fields that should be excluded from response.

Sample Response

{
  "link_sid": "f144a51a-20f5-4d2e-8864-0d889f212eda",
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "date_created": "2017-12-15T13:04:54.000Z",
  "date_accessed": null,
  "url": "http://mydomain3.com/LmBpfe",
  "destination_url": "http://destinationurl.com",
  "short_name": "LmBpfe",
  "mode": "redirect_temporary",
  "maximum_ttl": -1,
  "hits": 0
}

Attributes

Attribute Data Type Description
link_sid string Link secure ID
domain_sid string Domain secure ID
partner_sid string Partner secure ID
date_created string Date when the link was created
date_accessed string Date when the link was accessed
url string URL to get an access to destination_url, generated automatically
destination_url string Site where user will be sent to
short_name string Short portion of the url. If omit, it will be automatically generated. Unique with domain_sid
mode string May be "proxy" or "redirect" (301). Defaults to "redirect" = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
maximum_ttl integer Link lifetime in seconds, -1 means eternity
hits integer Link hits quantity

Patch Link

This call will modify fields of a particular link object which secure ID is specified. Note: only parameters specified in the call will be updated. The other will preserve their current value.

METHOD URL
PATCH /shortener/links/{link_sid}

Sample URL


curl -X PATCH --header "Accept: application/json"  -d "{"name":"av_2bb"}" -u [your_user_name]:[your_password] '{"destination_url": "http://newdestination.com", "short_name": "shortname"}' 'https://api.carrierx.com/core/v2/shortener/links/ef3a533d-51d0-4777-a4b5-bc97ab0825d7'

Parameters

Parameter Data Type Description
link_sid string Link secure ID
body object body Fields to be modified

Sample Response

{
  "link_sid": "ef3a533d-51d0-4777-a4b5-bc97ab0825d7",
  "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
  "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
  "date_created": "2017-12-15T13:03:02.000Z",
  "date_accessed": null,
  "url": "http://mydomain3.com/shortname",
  "destination_url": "http://newdestination.com",
  "short_name": "shortname",
  "mode": "redirect_temporary",
  "maximum_ttl": -1,
  "hits": 0
}

Attributes

Attribute Data Type Description
link_sid string Link secure ID
domain_sid string Domain secure ID
partner_sid string Partner secure ID
date_created string Date when the link was created
date_accessed string Date when the link was accessed
url string URL to get an access to destination_url, generated automatically
destination_url string Site where user will be sent to
short_name string Short portion of the url. If omit, it will be automatically generated. Unique with domain_sid
mode string May be "proxy" or "redirect" (301). Defaults to "redirect" = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
maximum_ttl integer Link lifetime in seconds, -1 means eternity
hits integer Link hits quantity

Update Link

This call will update a particular link object which secure ID is specified.

METHOD URL
PUT /shortener/links/{link_sid}

Sample URL


curl -X PUT --header "Accept: application/json"  --data-binary'{ "link_sid": "ef3a533d-51d0-4777-a4b5-bc97ab0825d7", "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e", "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x", "date_created": "2017-12-15T13:03:02.000Z", "date_accessed": null, "url": "http://mydomain3.com/shortname", "destination_url": "http://newdestination.com", "short_name": "shortname", "mode": "redirect_temporary", "maximum_ttl": -1, "hits": 0 }' -u : 'https://api.carrierx.com/core/v2/shortener/links/ef3a533d-51d0-4777-a4b5-bc97ab0825d7'

Parameters

Parameter Data Type Description
link_sid string Link secure ID
body object body Fields to be modified

Sample Response

  {
    "link_sid": "ef3a533d-51d0-4777-a4b5-bc97ab0825d7",
    "domain_sid": "3ccfa22e-6927-4856-a088-0c4df348f26e",
    "partner_sid": "ypdm9zW2d-f3rH.mljbilExkNXL2Zi5x",
    "date_created": "2017-12-15T13:03:02.000Z",
    "date_accessed": null,
    "url": "http://mydomain3.com/shortname",
    "destination_url": "http://newdestination.com",
    "short_name": "shortname",
    "mode": "redirect_temporary",
    "maximum_ttl": -1,
    "hits": 0
  }

Attributes

Attribute Data Type Description
link_sid string Link secure ID
domain_sid string Domain secure ID
partner_sid string Partner secure ID
date_created string Date when the link was created
date_accessed string Date when the link was accessed
url string URL to get an access to destination_url, generated automatically
destination_url string Site where user will be sent to
short_name string Short portion of the url. If omit, it will be automatically generated. Unique with domain_sid
mode string May be "proxy" or "redirect" (301). Defaults to "redirect" = ['proxy_pass', 'redirect_temporary', 'redirect_permanent']
maximum_ttl integer Link lifetime in seconds, -1 means eternity
hits integer Link hits quantity






CallBacks

The CarrierX API enables CallBacks to be sent to your hosted endpoint.

Assigning a CallBack URL through the partners API will allow you to receive Global feedback on all SMS activity associated to the Partner account. For example, if your partner account has three SMS enabled DIDs assigned to it, then the callback URL will receive JSON responses from all three DIDs. Conversely, if you set a CallBack using the /dids API, you will only receive a JSON response related to that specific DID. Please note that once you have set a CallBack value at the level of the DID, you will override whatever CallBack you have set at the level of the partner for that DID.


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": “18448441322",
  "to_did": “15624371411"
}
Attribute Data Type Description
price string The associated price
message_segments integer Number of segments in the message
mnc string Mobile network code
status string Status of the message
  • created
  • queued
  • sending
  • sent
  • receiving




System Codes

This section lists the HTTP status codes the API returns to each request.


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 Response

Response Code Text Description
401 Unauthorized The request requires user authentication.
403 Forbidden The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
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.