Introduction

The CarrierX service offers a hosted FlexML Application Endpoint type that enables creating voice workflows by passing XML instructions. Using a variety of verbs, the endpoint interprets instructions and uses them to play recordings, route calls via DTMF inputs, and implement call flow logic.

Using the REST API

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

Credentials

API requests require authentication. To obtain a free CarrierX account and gain credentials, provide an email address on the homepage . The credentials used to log in to the CarrierX website are the same credentials used to access the Core API.

Prior to creating calls , a FlexML Application Endpoint needs to be created. See the Configuring Application Endpoints Quick Start Guide for step-by-step instructions on creating an endpoint.

In the JSON response for a newly created FlexML Application Endpoint, there will be login and password values. These are the credentials to use when working with that particular endpoint. Each endpoint has its own credentials. Entering the Core API credentials instead of the endpoint-specific credentials when working with the FlexML API will return the error unauthorized .

Sample Curl Command

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

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

Sample JSON Response

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

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

Requests

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

The FlexML API has the following base URL:

https://api.carrierx.com/flexml/v1

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

Responses

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

For a comprehensive list of returned attributes refer to the Account Object Reference , Call Object Reference , and DID Object Reference .

Pagination

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

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

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

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

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

Sample Curl Command

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

Sample JSON Response

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

Pagination Quick Reference

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

Relational Operator Quick Reference

Field Filtering

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

Refer to the specific object to determine which fields can be included and excluded from the JSON responses. include_fields and exclude_fields accept comma-separated strings as values.

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

Sample Curl Command

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

Field Filtering Quick Reference

<Response>
  <Gather action="/path/to/handler" timeout="5">
    <Say>Please enter the extension of the party you would like to reach. </Say>
  </Gather>
  <Say>You did not enter an extension. </Say>
  <Hangup />
</Response>

Markup Language

FlexML, the CarrierX markup language, is used to create instructions for call logic. The basic components of the markup language are verbs, which dictate what type of action will be performed. Since the instructions are executed from top to bottom, the verbs should be ordered as such. Verbs are modified using supported attributes.

The Dial verb connects the calling party with the dialed party. Once the call is set up, the participants can start talking.

If the dialed number is not reached, or the call is terminated, CarrierX will make a POST or GET request to the action URL. The verbs listed after an action URL will not be executed. If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

Supported Attributes

These attributes can be used to modify the verb Dial . They are inserted as name-value pairs in the start-tag.

Sample FlexML

In this example, the phone number in the Number tags will be dialed. The call total time will be limited to 15 seconds. The called party will be able to hang up by pressing the * key. If an action URL is added to the Dial verb as an attribute, a request will be made to that URL if the phone number cannot be reached, or when the call ends.

<Response>
  <Dial timeLimit="15" hangupOnStar="true">
    <Number>15162065340</Number>
  </Dial>
</Response>

The Gather verb collects the digits that a caller enters into the phone keypad. The entered data from the keypad is passed to the action URL. In the case that no input has been entered, the call will move to the next verb in the FlexML instructions.

Supported Attributes

Sample FlexML

In the following sample FlexML instructions, once the party is reached, the called party will be prompted by verbal command to enter some digits. If an action URL is set, the URL will be queried once DMTF input has been gathered according to the specifications. In this case, if the action URL was set, it would be requested once the party has entered two digits because numDigits is set to 2 .

<Response>
  <Gather numDigits="2">
    <Say>Please enter the extension of the party you'd like to be connected to. </Say>
  </Gather>
</Response>

The following verbs can be nested in the verb Gather . These are the only two verbs that can be nested within another verb.

Say

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="/<file>.xml">
  <Say>Please enter two digits</Say>
  </Gather>
</Response>

Play

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="/<file>.xml">
  <Play><http://<file>.wav</Play>
  </Gather>
</Response>

Request Data

The following is an additional parameter and value that will be included in action requests. For a list of the other parameters and values to expect in action requests, refer to the FlexML Call Flow section.

Hangup will answer the call and then immediately hang up. To reject the call without answering, use Reject instead.

Sample FlexML

<Response>
  <Hangup/>
</Response>

Supported Attributes

Sample FlexML

This FlexML sample is re-assigning the statusCallbackUrl and statusCallbackMethod for this specific set of instructions.

<Response>
  <Override statusCallbackUrl="http://www.example.com/path/to/handler" statusCallbackMethod="GET" />
  <Play streaming="true" timeLimit="30">
    http://www.example.com/path/to/media.mp3
  </Play>
</Response>

Pause stops the next verb in the FlexML instructions from executing before the number of seconds has elapsed.

Supported Attributes

Sample FlexML

In this example, the called party will hear a welcome message, followed by a 15 second pause. Then the thank you message will play.

<Response>
  <Say>Welcome</Say>
  <Pause length=15/>
  <Say>Thank you for your time.</Say>
</Response>

Play will play a file to the caller. The file URL is passed in the element content. Once the Play file ends, CarrierX will make a POST or GET request to the action URL. The verbs listed after an action URL will not be executed. If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

If the Play file fails to play, a POST or GET request will be sent to the errorAction URL.

Supported Attributes

Sample FlexML

These FlexML instructions will play the file as a stream for the maximum duration of 30 seconds.

<Response>
  <Play streaming="true" timeLimit="30">
    http://www.example.com/path/to/media.mp3
  </Play>
</Response>

Supported File Formats

These are the format types that will be able to play.

Supported Protocols

These are the audio streaming protocols. http and https are supported when streaming is set to true or false . Use hls or rtmp to play streaming files only. Note that streaming must be set to true when using either hls or rtmp .

The Record verb records the conversation and stores it as an audio file in the specified container. Once the recording has ended, CarrierX will make a POST or GET request to the action URL. The verbs listed after an action URL will not be executed. If no action URL is set, the call flow will move to the next verbs in the FlexML instructions. If the recording fails, a POST or GET will be sent to the errorAction URL.

Accounts come with a limited amount of storage by default. To add more storage, email support@carrierx.com or contact your account representative.

Supported Attributes

Sample FlexML

In this example, a background recording begins because recordSession is set to true . The recording is saved in the specified containerSid . Note that by default, the container used to store the recording will be the one specified in the Endpoint object. However, the container can be overridden by assigning a containerSid , as is shown here. The system will automatically generate a file inside of the container, unless a fileSid is specified. The recording will fail if the container does not exist or is full. A failure will also occur if the file does not exist or is full.

<Response>
  <Record containerSid="ea55039a-3ee4-48cd-a1ff-dfb7751f1cec" recordSession="true"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Callback Returned Data

The following are additional parameters and values that will be returned in action requests. For a list of the other parameters and values to expect in action requests, refer to the FlexML Call Flow section.

The Redirect verb turns over the control of the call flow to another set of FlexML instructions located at a different URL. Any verb listed after Redirect gets ignored.

Supported Attributes

Sample FlexML

In this example, the flow of the call will be redirected to the URL specified in the Redirect tags. This URL is requested using the GET method. The Say instruction after Redirect is ignored.

<Response>
  <Redirect method="GET">http://www.example.com/path/to/handler</Redirect>
  <Say>Thank you</Say>
</Response>

The Reject verb does not answer a call, but instead rejects it. To ensure the incoming call is unanswered, put Reject as the first verb in Response .

Supported Attributes

Sample FlexML

In this example, the call will be immediately rejected and reject message to the carrier will be busy .

<Response>
  <Reject reason="busy"></Reject>
</Response>

Say converts written text to voice. This is a verbal message that the caller will hear. Supported attributes can be added to customize the type of voice and the number of repetitions of the message. Note that the maximum number of characters that can be inputted into the Say verb is 1,024.

Integers added into the Say verb will be read according to how they are entered. "123" will be read as "one hundred twenty-three" and 1 2 3 will be read as "one two three". To add a pause in the message, close out the Say tag, insert a Pause tag, and then open a new Say tag with the rest of the text.

Supported Attributes

Sample FlexML

In this example, a thank you message will be read twice to the caller because loop is set to 2 . Between loops one and two, there will be a five second pause because loopPause is set to 5 .

<Response>
  <Say voice="woman" loop="2" loopPause="5">Thank you for calling customer service</Say>
</Response>

Sms

The Sms verb sends an SMS message to a phone number during a phone call. Use the attributes to define the receiving and sending parties. If an action attribute is added to the Sms verb, all verbs remaining in the current FlexML instructions are ignored. If no action is provided, the call flow will move to the next verb in the current FlexML instructions.

Supported Attributes

Sample FlexML

In this example, an SMS message is sent to the phone number value of to . The message body is added between the Sms tags. If no to and from attributes are added to the Sms tag, the sending party will default to the calling party, and the receiving party will default to the called party.

<Response>
  <Sms to="15162065317">Have a great day!</Sms>
</Response>

Accounts

Each FlexML Application Endpoint has its own Account object. The Account object holds the settings for that specific FlexML Application Endpoint. Changes made to the Account object will affect all of the calls associated with that particular account.

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

This request shows data for the currently logged in Account. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts?offset=0&limit=10&order=name' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
          "date_created": "2018-09-20T21:56:49.000Z",
          "error_handler": "basic",
          "login": "sample_flexml_984",
          "method": "POST",
          "name": "sample_flexml",
          "url": null
      }
  ],
  "limit": 10,
  "offset": 0,
  "pagination": {},
  "total": 1
}

A successful request will return a 200 response code with a serialized copy of the Account object . Refer to the HTTP Status Codes section for common errors.

The request will return information for an account by its secure ID. The secure ID is passed in the query URL. This request is enabled for Field Filtering .

Path Arguments

Sample Curl Command

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts/e4d82fab-b613-4c0d-bd40-a9f94e8263c7' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
  "date_created": "2018-09-20T21:56:49.000Z",
  "error_handler": "basic",
  "login": "sample_flexml_984",
  "method": "POST",
  "name": "sample_flexml",
  "url": null
}

A successful request will return a 200 response code with a serialized copy of the Account object . Refer to the HTTP Status Codes section for common errors.

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

Path Arguments

Body Arguments

Sample Curl Command

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/accounts/592210fa-8126-4255-bc77-c8dedb6af834' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"POST"}' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

{
  "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
  "date_created": "2018-09-20T21:56:49.000Z",
  "error_handler": "basic",
  "login": "sample_flexml_984",
  "method": "POST",
  "name": "sample_flexml",
  "url": null
}

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

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

Note that all of the parameters that appear in the object that is being modified should be included in the request body. Failing to add all of the parameters will result in an error. An error will also occur when trying to change values that cannot be updated.

Path Arguments

Body Arguments

curl -X PUT \
'https://api.carrierx.com/flexml/v1/accounts/1d4adc32-45d1-4789-9780-928049e2bce1' \
-H 'Content-Type: application/json' \
--data-binary '{"account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1", "date_created": "2018-09-20T21:56:49.000Z", "error_handler": "basic", "login":"sample_flexml_984", "method":"GET", "name":"sample_flexml", "url":"", "password":"sample_password"}' \
-u '[your_user_name]:[your_password]'

DIDs

DIDs are phone numbers rented through CarrierX. They serve as calling_did values.

DID Object Reference

This section describes the fields of the DID object. These fields and values are returned as the JSON object that gets returned with successful requests.

curl -X GET \
'https://api.carrierx.com/flexml/v1/dids' \
-u '[your_user_name]:[your_password]'

Get DID by SID

curl -X GET \
'https://api.carrierx.com/flexml/v1/dids/d72c0ec3-c21d-4db1-8877-690cb9644fbc' \
-u '[your_user_name]:[your_password]'

Update DID

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/dids/70999383-9162-405f-8f62-a550a416ee21' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"GET"}' \
-u '[your_user_name]:[your_password]'

curl -X PUT \
'https://api.carrierx.com/flexml/v1/dids/70999383-9162-405f-8f62-a550a416ee21' \
-H 'Content-Type: application/json' \
--data-binary '{ "phonenumber": "15162065319", "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc", "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1", "url": "http://ow-fcc4d-app01.int/pvtest/pi", "status_callback_method": "POST", "method": "GET", "country_code": null, "in_country_format": null, "international_format": null }' \
-u: '[your_user_name]:[your_password]'

HTTP Status Codes

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

Success Response

Error Responses