Introduction

The CarrierX service offers a hosted FlexML Application Endpoint type that enables creating voice work-flows 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.

Refer to the FlexML products page for quick start guides and video tutorials. These hold walk-through instructions on configuring FlexML endpoints, building simple voice applications, configuring inbound calls, and making outbound calls.

Using the REST API

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

Using Postman

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

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

For more information, see our Getting Started with Postman Quick Start Guide.

Main Conventions

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

Credentials

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

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

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

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

API requests require authentication. To obtain a CarrierX account and gain credentials, please submit a request through our Contact Us page. The Core API uses a bearer token, and the endpoint APIs (Conference, FlexML, and Mediator) use a login and password.

Prior to making requests, a FlexML Application Endpoint needs to be created. See the Configure an Application Endpoint quick start guide for step-by-step instructions on creating an endpoint.

Each of the application endpoints has different login and password values. Entering the Core API token credentials instead of the endpoint-specific credentials when working with the Conference, FlexML, or Mediator APIs will return the error unauthorized.

Requests

Sample request to create Conference endpoint.

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

The requests in CarrierX API are made using the standard REST notation, typical for web services. This includes the URL, to which the request will be sent, the request method, the request related headers, and, optionally, a payload.

Request URL

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

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

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

Request Methods

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

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

POST

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

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

GET

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

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

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

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

PATCH/PUT

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

Sample PATCH request to modify or add a new name record of the nested attributes object.

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

The successful request returns the serialized JSON copy of the created object together with the nested object.

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

Sample PATCH request to add a new name2 record of the nested attributes object of the same Partner object.

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

The successful request returns the serialized JSON copy of the created object together with the modified nested object.

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

Sample PATCH request to modify the entire nested attributes object of the same Partner object.

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

The successful request returns the serialized JSON copy of the created object together with the nested object.

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

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

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

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

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

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

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

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

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

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

DELETE

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

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

Additional Request Parameters

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

Responses

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

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

Pagination

This request returns Call objects starting with the second record available, and returns a maximum of 4 records.

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

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

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

The three optional parameters for pagination are: offset, limit, and order. 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. Two values are 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 by 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.

Pagination Quick Reference

Result Filtering

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

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

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

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

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

Result Filtering Quick Reference

Field Filtering

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

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

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

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

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

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

Field Filtering Quick Reference

HTTP Errors

The FlexML API uses the following HTTP error codes:

FlexML Call Flow

FlexML instructions are used to create custom call flows for both inbound and outbound calls. This section goes over requests, responses, and status callbacks.

FlexML Requests

For inbound calls, the url and method from the DID object will be used. If the url value in the DID object is not set, then the url and method values from the Account object will be used instead.

For outbound calls, these values are set in the Call object. CarrierX will make a request to the URL provided, and expects to receive FlexML instructions in the response. These instructions contain a set of ordered commands that will be used to handle the call. The method value is the type of request that will be made to the url, either POST or GET.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Data about the call will be passed in the request body in JSON format if the method is POST. Data will be passed as query parameters if the method is GET.

CallStatus Values

The following are values that appear in the CallStatus field.

In addition to the Request Data described in the table above, data can also include the URL holding the recording audio and the duration of the recording in seconds. Callback data depends on the type of FlexML instructions being executed.

Please refer to the individual verb sections for additional data returned when using those verbs.

FlexML Responses

The response to the CarrierX request should include FlexML instructions. Each set of FlexML instructions is wrapped within Response wrapper start and end tags. Tags nested inside of Response tags are called verbs, and attributes that modify these verbs are simply referred to as supported attributes. The verbs are executed from top to bottom. However, some instructions will break the flow, and the remainder of the verbs will not be executed.

Sample FlexML

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

In this example, once the call has been connected, the called party will be prompted by the Say message to enter the extension of the party they are trying to reach. The called party has five seconds to enter the extension because timeout is set to 5. If digits are entered, the action URL will be requested, and the FlexML instructions at that URL will be executed. The rest of the FlexML instructions in the current instructions will be ignored.

If the called party does not enter digits after the 5 seconds has elapsed, the instructions will proceed to the Say verb below Gather. Then the Hangup verb will be executed.

Status Callbacks

Data about completed calls can be received by setting status_callback_url and status_callback_method in the Call object or the DID object. The response to this request is not used. If a status_callback_url is set on both the Call object and DID object, the URL set on the Call object will be used.

The status_callback_url and status_callback_method can also be overridden using the Override verb in a FlexML response. Please refer to the Override section for more information.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallDuration":8,
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "PlaybackUrl":"https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3",
    "PlayOffset":37,
    "RequestMethod":"GET",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

These status callback fields are in addition to the fields listed in the Requests section.

FlexML Verbs

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.

Amd (experimental)

In this example, the verb Amd will attempt to detect whether or not the other party is human or machine. If no greeting has been made before 5 seconds, the other party is determined to be machine. If the greeting exceeds 2 seconds, then the other party is determined to be machine. Additionally, the other party is determined to be machine if the post-greeting silence exceeds 0.5 seconds.

When a determination has been made, or the totalAnalysisTime of 10 seconds has elapsed, a callback will be sent to the action URL via POST method.

<Response>
  <Amd action="/api/v1/call-control/message/amd/15162065340"
  method="POST"
  initialSilence="5000"
  greeting="2000"
  afterGreetingSilence="500"
  totalAnalysisTime="10000" />
</Response>

The experimental Amd verb attempts to determine whether the other party is human or machine. The determination of the other party’s status will be returned in a callback and possible returned values will be as follows.

AMD Callback Attributes

AMDStatus Values

These values can be returned as AMDStatus.

Supported Attributes

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

Dial

To simply dial the number, include it directly inside the Dial verb without using the Number noun. In this case, FlexML instructions cannot include any additional parameters for the dialed number. In this example, the phone number inside the Dial 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">15162065340</Dial>
</Response>

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 Dial verb. They are inserted as name-value pairs in the start-tag.

Number Supported Attributes

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. Once the call is answered, the wait of two seconds will be performed (the total length of four , characters, each equal to 0.5-second delay), after that the 1928 DTMF tones will be played to the dialed number.

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

The Number noun, which can be nested inside the Dial verb, contains the DID number to be dialed. It supports the following attributes:

Simultaneous Ring to Several Numbers

In this example, the phone numbers in the Number tags will be dialed all at the same time. The first person to answer is connected to the caller.

<Response>
  <Dial>
    <Number>12345645585</Number>
    <Number>96846465465</Number>
    <Number>98133217461</Number>
  </Dial>
</Response>

CarrierX supports dialing to several numbers at once. You need to specify the numbers in the Number noun tags inside the Dial verb. The first person to answer will be connected to the caller. The calls to the other numbers will be hung up.

Query Arguments

Dial supports sending custom headers using the additional query arguments in it. You can use the ? character inside the Number noun, e.g.:

<Number>15162065340?X-CustomHeader1=ABC&X-CustomHeader2=DEF</Number>

Dtmf

In these sample FlexML instructions, the phone number in the Dial verb is dialed, and then the integers within the Dtmf tags are entered. Each comma within the Dtmf tag is a 0.5 second delay.

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

The Dtmf verb enters the symbols within its tags.

Gather

In these 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>

Say will read out the text within its tags.

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

Play will play the file within its tags.

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

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

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

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

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits": "",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

The following is an additional parameter and value that will be included in action requests.

Hangup

The following will hang up on the caller. Instructions after the Hangup verb will not run.

<Response>
  <Hangup/>
</Response>

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

Override

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

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

Supported Attributes

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

Pause

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>

Pause stops the next verb in the FlexML instructions from executing before the number of seconds has elapsed. The Pause verb is the same as the Wait verb.

Supported Attributes

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

In this example, the caller will hear a welcome message and will be asked to say something. After that the wait for the audio input from the caller (with a maximum delay of 15 seconds before giving up) will start.

<Response>
  <Say>Welcome</Say>
  <Say>Please announce yourself</Say>
  <Pause noise="true" minNoise="2000" silence="true" minSilence="2500" length="15" />
</Response>

Let’s say, the caller starts talking five seconds after the call started and speaks for four seconds. This means that waiting for the audio took nine seconds totally (five of initial silence + four of audio), the remaining time will be spent on waiting for silence, and is equal to six seconds maximum. If 2.5-seconds silence follows, the whole pause will be 11.5 seconds. After that FlexML switches to the next instructions.

Play

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

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

The same result can be achieved if file_sid is used together with the File noun instead of the direct link.

<Response>
  <Play timeLimit="30">
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

Play will play a file to the caller. There are two ways to specify the file to be played:

• pass the file URL between the Play tags;
• nest the File noun inside the Play verb and use the file_sid attribute of the File Object which can be obtained using the Get Files request.

Once the file stops playing, 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

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

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits":"",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "PlaybackUrl":"https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3",
    "PlayOffset":37,
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Supported File Formats

These are the format types that will be able to play: aac, al/alaw, flac, g722, m3u8, mp3, mp4/mp4a, ogg, ul/ulaw, and wav

Supported Protocols

The audio streaming protocols are hls, http, https, and rtmp. 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.

Record

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

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

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

Supported External Storage

The following external storage services are supported to store the recording data:

• Amazon Simple Storage Service (AWS S3)
• Google Cloud Platform (GCP)
• Microsoft Azure Blob storage

You will need to provide the credentials and specify the storage location for each of the external storage used. Only one external storage can be used at a time. Refer to the tables below to learn what parameters you need to specify for each storage type.

In this example, the background recording is saved to the specified awsBucketName of Amazon S3.

<Response>
  <Record recordSession="true" awsAccessKey="_AWS_ACCESS_KEY_" awsBucketName="_AWS_BUCKET_NAME_" awsSecretKey="_AWS_SECRET_ACCESS_KEY_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Amazon Simple Storage Service

In this example, the background recording is saved to the specified gcpBucketName Google Cloud Platform.

<Response>
  <Record recordSession="true" gcpAccessToken="_GCP_ACCESS_TOKEN_" gcpBucketName="_GCP_BUCKET_NAME_" gcpProject="_GCP_PROJECT_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Google Cloud Platform

In this example, the background recording is saved to the specified azureContainerName of Microsoft Azure Blob Storage.

<Response>
  <Record recordSession="true" azureAccountKey="_AZURE_ACCOUNT_KEY_" azureAccountName="_AZURE_ACCOUNT_NAME_" azureContainerName="_AZURE_CONTAINER_NAME_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Microsoft Azure Blob Storage

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.

Redirect

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

Reject

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

<Response>
  <Reject reason="busy"></Reject>
</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

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

Reject Reasons

Say

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>

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

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

Sms

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>

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

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

Wait

Wait stops the next verb in the FlexML instructions from executing before the number of seconds has elapsed. The Wait verb is the same as the Pause verb. Please refer to the Pause section.

API Reference

The FlexML API has the following sections: Accounts, Calls, and DIDs.

Use the Account object to modify call settings. Target the Call object to create, modify, and delete phone calls. The DID object holds modifiable data about phone numbers rented through CarrierX.

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.

Account Object

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.

Sample Account object:

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

Get Accounts

The following GET request returns accounts matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Account objects.

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

This request shows data for the currently logged-in Account.

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

Get Account by SID

The following GET request returns an account, targeted by secure ID.

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

A successful request will return a 200 response code with a serialized copy of the Account object.

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

This request will return data for an account, targeted by secure ID.

This request is enabled for Field Filtering.

Path Arguments

Update Account

The following PATCH request updates the Account object, targeted by secure ID, with the values in the request body.

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

A successful request will return a 200 response code with a serialized copy of the updated Account object.

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

This request updates an account, targeted by secure ID.

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

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

• A PUT request can be used to update an entire Account object. The account secure ID is passed in the query URL, and the entire Account object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• error_handler
• method
• url

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

Calls

Calls occur when the CarrierX system dials out to a phone number. FlexML instructions are added to the call flow by setting the url parameter.

Call Object

This section goes over the parts of the Call object. These fields and values make up the JSON response that gets returned when a request is successful. In this section, there is also information about the optional fields that can be added to further customize calls. These fields can be added when initially creating the binding, or they can be added later using PATCH or PUT requests.

Sample Call object:

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "2f367eb5-adc6-4413-b603-533e2a8f0804",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T20:59:18.094Z",
    "delay": 0,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

Attribute Object

The following are attributes that can be added to the Call object. Note that custom attributes can also be added in the same way as the following attributes are added.

Create Call

The following POST request creates a call.

curl -X POST \
'https://api.carrierx.com/flexml/v1/calls' \
-H 'Content-Type: application/json' \
--data-binary '{"calling_did":"15162065319", "called_did":"15162065318"}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Call object.

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "2f367eb5-adc6-4413-b603-533e2a8f0804",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T20:59:18.094Z",
    "delay": 0,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request creates a call.

Body Arguments

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

Required fields to create a call are:

• called_did
• calling_did

The calling_did should be one of the DIDs assigned to the FlexML endpoint.

To schedule a call to happen in the future, set the delay parameter to the amount of seconds to wait before the call is executed.

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

Get Calls

The following GET request returns calls matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of Call objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
            "attributes": {},
            "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
            "called_did": "15162065317",
            "calling_did": "15162065319",
            "date_created": "2018-10-16T21:56:49.000Z",
            "delay": 9993,
            "method": "POST",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request will return a list of Call objects scheduled for some time in the future.

All Call objects that are returned will have a delay parameter of more than 0. By default, the delay parameter is set to 0, so calls will be executed immediately after they are created.

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

Get Call by SID

The following GET request returns a call, targeted by secure ID.

curl -X GET \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the Call object.

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T21:56:49.000Z",
    "delay": 9916,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

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

The call_sid must be passed in the path arguments.

This request is enabled for Field Filtering.

Path Arguments

Update Call

The following PATCH request updates the Call object, targeted by secure ID, with the values in the request body.

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-H 'Content-Type: application/json' \
--data-binary '{"delay": 1000}' \
-u '[your_user_name]:[your_password]'

A successful request will return a 200 response code with a serialized copy of the updated Call object.

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T21:56:49.000Z",
    "delay": 1000,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request updates a call, targeted by secure ID.

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

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

• A PUT request can be used to update an entire Call object. The call secure ID is passed in the query URL, and the entire Call object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• attributes
• called_did
• calling_did
• delay
• method
• status_callback_method
• status_callback_url
• url

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

Delete Call

The following DELETE request deletes a call, targeted by secure ID.

curl -X DELETE \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-u '[your_user_name]:[your_password]'

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

This request deletes a call, targeted by secure ID.

Path Arguments

DIDs

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

DID Object

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.

Sample DID object:

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": null,
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": null,
    "international_format": null,
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": "http://ow-fcc4d-app01.int/pvtest/pi"
}

Get DIDs

The following GET request returns DIDs matching the criteria in the request URL.

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

A successful request will return a 200 response code with a list of DID objects associated with the endpoint.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
            "country_code": null,
            "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
            "in_country_format": null,
            "international_format": null,
            "method": "POST",
            "phonenumber": "15162065319",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": "http://ow-fcc4d-app01.int/pvtest/pi"
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of DIDs associated with a FlexML Application Endpoint.

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

Get DID by SID

The following GET request returns a DID object, targeted by secure ID.

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

A successful request will return a 200 response code with a serialized copy of the DID object.

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": null,
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": null,
    "international_format": null,
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": "http://ow-fcc4d-app01.int/pvtest/pi"
}

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

This request is enabled for Field Filtering.

Path Arguments

Update DID

The following PATCH request updates the DID object, targeted by secure ID, with the values in the request body.

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]'

A successful request will return a 200 response code with a serialized copy of the updated DID object.

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": null,
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": null,
    "international_format": null,
    "method": "GET",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": "http://ow-fcc4d-app01.int/pvtest/pi"
}

This request updates a DID, targeted by secure ID.

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

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

• A PUT request can be used to update an entire DID object. The DID secure ID is passed in the query URL, and the entire DID object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• account_sid
• did_sid
• method
• status_callback_method
• status_callback_url
• url

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