FlexML API Reference

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.

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.

Run in Postman

Main Conventions

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

create The attribute can be set when the user creates the object using the POST method.
update The attribute can be modified when the user updates the object using either PATCH or PUT methods.
read only The attribute is set by the system and the user can neither set nor modify it.

Authentication

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

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

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

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 1
}

All CarrierX API requests require authentication. The first step to using CarrierX API is obtaining a CarrierX account and gaining credentials. To do so, please submit a request through our Contact Us page.

Currently, CarrierX API requests use two types of authentication:

Prior to making requests, you need to create a FlexML application endpoint. Refer to the FlexML Endpoint quick start guide for step-by-step instructions on creating a FlexML endpoint.

Requests

Sample request to create Conference endpoint

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

The requests in CarrierX API are made using the standard REST notation, typical for web services.

A simplest request will have the following structure:

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

Other request may have additional structure elements which include:

Request URL

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

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

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

Request Methods

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

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

POST

Sample POST request that creates a trunk

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

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

GET

Sample GET request that returns the currently logged-in partner

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

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

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

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

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

PATCH/PUT

Sample PATCH request that modifies or adds a new name record of the nested attributes object

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

Response The serialized JSON copy of the created object together with the nested object

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

Sample PATCH request that adds a new name2 record of the nested attributes object of the same Partner object

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

Response The serialized JSON copy of the created object together with the modified nested object

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

Sample PATCH request that modifies the entire nested attributes object of the same Partner object

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

Response The serialized JSON copy of the created object together with the nested object

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

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

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

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

  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

Sample DELETE request that deletes an endpoint

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

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

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

Rate Limiting

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

Responses

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

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

HTTP Status Codes

Typical 200 status code in the response

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

The FlexML API uses the following HTTP status codes:

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

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

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

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

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

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

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

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

The above status codes are common for all requests.

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

Response Objects

Typical formatted JSON object in the response

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

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

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

With jq, the request will look like this:

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

Pagination

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

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

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

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

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

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

The pagination parameters include:

limit

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

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

order

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

offset

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

after/ before

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

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

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

Parameter Data Type Description
after string The secure ID of the object. The response will include only the results which follow the specified secure ID in the list of the object secure IDs.
before string The secure ID of the object. The response will include only the results which precede the specified secure ID in the list of object secure IDs.

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

Object Method Sorting (‘order’) Values
Call Detail Record Get Call Detail Records method date_stop
SMS Detail Record Get Message Detail Records method date_insert

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response

The JSON response for a successful query using the pagination parameters will include the following attributes:

Attribute Data Type Description
count integer The number of items present in the response.
has_more boolean Whether or not there are more records existing outside of the queried parameters (e.g., if the number of items that exist exceeds the limit value, the has_more value in the response will be set to true).
items array of objects The list of the objects which match the request with the pagination query parameters applied.
limit integer The limit value applied to the request.
offset integer The offset value applied to the request.
pagination object The links that allow getting the objects which precede or follow the objects in the response due to the offset or after/ before arguments used in the request. This attribute will be an empty object if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include the next or previous URLs, or both of them.
total integer The total number of the queried objects that match the search criteria. This value will be set to null with the uncountable objects (call detail records, messages, etc.)

Result Filtering

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

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

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

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

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

Result Filtering Quick Reference

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

Field Filtering

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

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

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

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

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

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

include_fields and exclude_fields accept comma-separated strings as values.

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

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 the JSON format if the method is POST. Data will be passed as query parameters if the method is GET.

Attribute Data Type Description
AccountSid string The account secure ID. This field is not yet supported and will be blank.
ApiVersion string The API version used to make the call.
CallerName string The CNAM of the calling party.
CallSid string The call secure ID. This value will remain the same throughout the duration of the call.
CallStatus string Denotes if an error has occurred. Refer to the table below for a list of values that appear in this field.
Direction string Denotes whether the call was inbound or outbound.
ForwardedFrom string Contains the phone number in the Diversion header, if present. This is used in cases such as conditional call forwarding. Note that not all carriers support passing this information in the header.
From string The calling party phone number, in the E.164 format.
OriginalFrom string The calling party phone number in a raw format, received directly from the carrier. Note that in development, From will generally be used.
OriginalTo string The phone number that was dialed in a raw format, received directly from the carrier. Note that in development, To will generally be used.
RequestUrl string The URL of the FlexML that was running to trigger the current request.
To string The phone number that is dialed, in the E.164 format.

CallStatus Values

The following are values that appear in the CallStatus field.

Value Description
busy There was a busy signal.
cancel The calling party canceled the call instead of answering it.
completed The call was answered normally.
failed The call failed to go through. There are a number of reasons why this can happen, including that the phone number was not valid or all channels were busy.
noanswer There were too many rings without an answer.

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="http://www.example.com/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.

Attribute Data Type Description
CallDuration integer The duration of the call in seconds.
PlaybackUrl string The URL of the file that was played.
PlayOffset integer The position of the playback from the beginning of the file when the call ends (either played or skipped to using DTMF controls).
RequestMethod string The type of request made to the RequestUrl, either POST or GET.
RequestUrl string The initial URL to which the request was made, as set in the Call object or DID object.

FlexML Syntax

FlexML, the CarrierX markup language, is used to create instructions for call logic.

The language is much like XML. It consists of special words included into opening and closing tags. Some of the tags are self-closing, i.e., they do not require a closing tag. Some of the tags can contain additional attributes in the start-tag. And some of the tags can nest values and even other tags between opening and closing tags.

The basic components of the markup language are verbs and nouns.

Amd (experimental)

In this example, the Amd verb 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 human 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="http://www.example.com/path/to/handler"
  method="POST"
  initialSilence="5000"
  greeting="2000"
  afterGreetingSilence="500"
  totalAnalysisTime="10000" />
</Response>

AMD stands for ‘Answering Machine Detection’. 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

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

{
  "AccountSid": "",
  "AMDCause": "HUMAN-500-500",
  "AMDStatus": "HUMAN",
  "ApiVersion": "2.0",
  "CallerName":"",
  "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
  "Direction":"inbound",
  "From":"15162065338",
  "OriginalFrom":"+15162065338",
  "OriginalTo":"15162065337",
  "RequestUrl":"https://sampleurl.com/example",
  "To":"15162065337"
}
Attribute Data Type Description
AMDCause string The reasoning for the determination of AMDStatus.
AMDStatus string The determination made about the other party, whether they are HUMAN or MACHINE. Alternatively, the determination can also be NOTSURE or HANGUP. Please refer to the table below for values that can be returned.

AMDStatus Values

These values can be returned as AMDStatus.

Value Description
HANGUP The other party hung up before a determination could be made.
HUMAN The other party is determined to be human.
MACHINE The other party is determined to be machine.
NOTSURE It was not determined definitively whether the other party is human or machine.

Supported Attributes

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

Attribute Data Type Description
action string Control is passed to this URL after the determination is made whether the other party is human or machine.
afterGreetingSilence integer The length of silence in milliseconds after a greeting is detected. If this number of seconds is exceeded, then the other party is determined to be human.
betweenWordSilence integer The minimum duration in milliseconds of silence after a word to consider the following audio a new word.
greeting integer The maximum length in milliseconds of a greeting. If this number of seconds is exceeded, the other party is determined to be machine.
initialSilence integer The maximum duration of silence in milliseconds before the greeting will begin. If this second value is exceeded, the other party is determined to be machine.
maximumNumberOfWords integer The maximum number of words in the greeting. If this value is exceeded, the other party is determined to be machine.
maximumWordLength integer The maximum duration of voice in milliseconds to be considered a word.
method string The type of request made to the action URL, either POST or GET.
minimumWordLength integer The minimum duration of voice in milliseconds to be considered a word.
silenceThreshold integer A number between 0 and 32767 that is used as the maximum level of noise to be considered silence.
totalAnalysisTime integer The maximum duration in milliseconds allowed for the algorithm to decide whether the other party is human or machine.

Nesting Rules

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.

When the call is ended successfully, or the dialed number is not reached, or the call is terminated, CarrierX will make a POST or GET request to the action URL.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

You can also place a phone number inside the Number noun. This is done to allow specifying the additional parameters (e.g., sendDigits) when dialing a phone number. Refer to the this section for more information about the Number noun.

Additionally, you can use the Number noun for the simultaneous ring to several numbers feature.

Supported Attributes

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

Attribute Data Type Description
action string The link to another set of FlexML instructions. A request will be made to this URL when the call is ended or if the dialed party is not available. If no action URL is set, the rest of the verbs in the current FlexML instructions will be executed. The URL can be absolute or relative.
callerId string The phone number that will appear on the caller ID of the called party. This phone number must be on the account, or have custom permission set up.
callerName string The calling party CNAME that is used in the from field.
confirmKey string The key that the called party must press to start the phone talk. Values accepted in this field are: 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, #, and *.
confirmSound string The URL of the audio that contains the instructions for the key from the confirmKey field. It informs the called party which key they must press to start the talk.
containerSid string The secure ID of the container to which the recording will be written.
hangupOnStar boolean If this value is set to true, pressing * will hang up the call with the dialed number, and continue with the next FlexML instructions. Until * is pressed, the rest of the FlexML instructions will not be executed.
method string The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
record string Determines whether or not to record the outbound call until hangup. Values accepted in this field are:
  • do-not-record for the call not to be recorded (the same effect as when the record attribute is not specified).
  • record-from-answer for recording to start from the moment the call is answered.
  • record-from-ringing for the recording to start from the moment the ringing begins.
The default value is do-not-record.
recordDirection string The direction of the call that will be recorded. Values accepted in this field are:
  • any to allow recording of both called and calling parties.
  • in to allow recording of the calling party only.
  • out to allow recording of the called party only.
The default value is any.
recordingStatusCallback string A callback is sent to this URL after the recording has ended.
recordingStatusCallbackEvent string The comma-separated list of events to be notified about. Options are completed, to indicate that the recording is successful, and failed, to indicate that the recording has failed. The default value is "completed,failed".
recordingStatusCallbackMethod string The method, either POST or GET that the callback to recordingStatusCallback is sent. The default value is POST.
ringing string Phone ringing management. Values accepted in this field are:
  • false to return the 200 OK success response and send the data to the calling party from the dialed party; no music or ringing is generated.
  • music to playback the default music.
  • true to return the 180 Ringing informational response, the ringing sound must be generated by the party that receives this response.
timeLimit integer The maximum number of seconds that the call will last. The default value is 0, meaning that the call time is not limited.
timeout integer The number of seconds to wait for the destination number to answer. After the call times out, a request is made to the action URL. The default value is 30.
trim string Determines whether or not silence is removed from the beginning or ending of a recording. To trim the silence in the recording, set this field to trim-silence. The default value is do-not-trim.

Number Noun

In this example, 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>
    <Number sendDigits=",,,,1928">15162065340</Number>
  </Dial>
</Response>

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

Attribute Data Type Description
sendDigits string The DTMF tones that will be played when the call is answered. This is especially useful when dialing a phone number with an extension. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, ,, and the combinations of these characters. Each comma character defines a 0.5-second delay.

CarrierX allows dialing to several numbers at once using the Number noun. Refer to the Simultaneous Ring to Several Numbers section of the Dial verb for more information about this.

Query Arguments

In this example, two X- headers will be sent when dialing the phone number specified in the Number noun nested inside the Dial verb.

<Response>
  <Dial>
    <Number>15162065340?X-CustomHeader1=ABC&amp;X-CustomHeader2=DEF</Number>
  </Dial>
</Response>

The additional query arguments can be used to send custom headers inside the Number noun. Use the ? character after the phone number to add these headers. Several headers are joined with the XML-encoded & character.

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

<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 calling party. The calls to the other numbers will be hung up.

Nesting Rules

Dtmf

In these sample FlexML instructions, the phone number in the Dial verb is dialed, and then the characters 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. This can be useful when dialing a phone number with an extension.

Values accepted for the Dtmf verb are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, ,, and the combinations of these characters. Each comma character defines a 0.5-second delay.

Nesting Rules

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="http://www.example.com/path/to/handler">
    <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="http://www.example.com/path/to/handler">
    <Play>http://<file>.wav</Play>
  </Gather>
</Response>

The Gather verb collects the digits that a calling party 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.

The Say and Play verbs can be nested in the Gather verb.

Supported Attributes

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

Attribute Data Type Description
action string The link to another set of FlexML instructions that will be called after the input has been submitted, or when the timeout value has expired. The URL can be absolute or relative.
finishOnKey string This determines the single key that will act as the submit key. If no finishOnKey value is specified, the input will be submitted after the timeout is expired. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *. To disable this feature, add the _ value. The default value is #.
method string The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
numDigits integer The expected number of digits to be entered in order to submit data to the action URL. Integers entered into this field must be greater than or equal to 1. If the field value is not specified, any number of digits will be listened for. Other actions will be listened to, such as timeout and finishOnKey, to end the input.
timeout integer The number of seconds to wait for the calling party’s next input before moving to the action URL request. Note that this is the time allotted between individual DTMF input, not the total time allotted to enter all values. If there is a nested verb such as Play within the Gather verb, the timeout will begin after the end of that verb. For example, if you have a Play URL, the playback will play through and then the timeout value will begin. The default value is 5.
validDigits string The list of the digits (tone keys, which the user can press) that will be recognized by the Gather verb. Any key outside this list will be ignored. The default value is 1234567890#*abcdABCD.

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.

Attribute Data Type Description
Digits string The digits entered via DTMF.

Nesting Rules

Hangup

The following will hang up on the calling party. 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.

Nesting Rules

Override

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

This verb is added to the top of FlexML instructions and the URL passed will override the status_callback_url and status_callback_method of the Call object for that specific call.

Supported Attributes

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

Attribute Data Type Description
statusCallbackMethod string The method to override the status_callback_method value.
statusCallbackUrl string The URL to override the status_callback_url value.

Nesting Rules

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.

Attribute Data Type Description
length integer The pause duration in seconds. Integers entered into this field must be greater than or equal to 1. The default value is 1.
minNoise integer The amount of time in milliseconds when some audio is received from the other end and considered to be noise. This field and value are only applicable when noise is set to true.
minSilence integer The amount of time in milliseconds where no voice or audio is received from the other end to be considered silence. This field and value are only applicable when silence is set to true.
noise boolean Determines whether or not noise detection is on. If set to true, Pause will end after a period of noise is detected. If set to false or there is no noise noise detected, Pause will wait the full amount of time specified in the length attribute. The default value is false.
silence boolean Determines whether or not silence detection is on. If set to true, Pause will end after a period of silence is detected. If set to false or there is no silence detected, Pause will wait the full amount of time specified in the length attribute. The default value is false.

In this example, the calling party will hear a welcome message and will be asked to say something. After that the wait for the audio input from the calling party (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 calling party 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.

Nesting Rules

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 calling party. There are two ways to specify the file to be played:

Once the file stops playing, CarrierX will make a POST or GET request to the action URL.

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

Attribute Data Type Description
action string The URL containing the executable FlexML instructions that will be requested after the Play file ends.
background boolean Playback occurs in the background if this value is set to true. The audio file will continue to play, but control will pass to the next verb. The default value is false.
controlSkip integer The amount of seconds skipped for forwardOnKey and rewindOnKey. Integers entered into this field must be greater than or equal to 1. The default value is 60.
digits string This attribute provides an alternate syntax for the Dtmf verb and will enter the digits provided as a string. Note that this attribute should be used alone with the Play verb, and no URL should be included between the Play tags. Other supported attributes should be used with their own Play verb.
errorAction string The URL containing the executable FlexML instructions that will be requested if the Play file fails.
errorMethod string The method used to request the errorAction URL containing the executable FlexML instructions if the Play file fails. This method can be set as either POST or GET. The default value is POST.
forwardOnKey string Entering the value of this field on a keypad will fast forward the recording by the number of seconds set in controlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
informationAudioUrl string The audio that will play when informationOnKey is pressed. After this file has been played once, normal playback resumes.
informationOnKey string If this key is pressed, audio is paused and informationAudioUrl is played. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
loop integer The number of times that the file will be played. Integers entered into this field must be greater than or equal to 1. Setting this field to 0 will make the file play repeatedly until the call is ended. The maximum value accepted in this field is 100. The default value is 1.
loopPause integer The number of seconds between each repetition. Integers entered into this field must be greater than or equal to 1. The maximum value accepted in this field is 300. The default value is 0, meaning that there will be no pause between repetitions.
method string The HTTP method used to execute the request to the action URL. This method can be set as either POST or GET. The default value is POST.
minorControlSkip integer The amount of seconds skipped for minorForwardOnKey and minorRewindOnKey. Integers entered into this field must be greater than or equal to 1. The default is 60.
minorForwardOnKey string Entering the value of this field on a keypad will fast forward the recording by the number of seconds set in minorControlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
minorRewindOnKey string Entering the value of this field on a keypad will rewind the recording by the number of seconds set in minorControlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
pauseAudioUrl string The audio to play while playback is paused by pauseOnKey. This audio is played on loop. There is a default comfort noise.
pauseOnKey string Used to pause the playback of the recording by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
preBuffer integer The time in seconds that the remote file should be queued before playback is started, to avoid playback catching up with a download in progress. The default value is 0.
restartOnKey string Used to restart the paused playback by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
rewindOnKey string Entering the value of this field on a keypad will rewind the recording by the number of seconds set in controlSkip. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *.
skip integer The time in seconds into a file that it will start playing.
stopOnKey string Used to stop the playback by pressing one of the keys. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *. Note that you can enter multiple values in this field. For example, if you add the 3* value, then you will be able to stop the playback by entering either 3 or *.
streaming boolean Allows to play the stream file defined in the URL parameter. Set the value to false if the URL is a prerecorded file, and true if the URL has a real-time recording. Note that setting the streaming value to true will disable forwardOnKey and rewindOnKey. Refer to the sections below for information about supported file formats and protocols. The default value is false.
strictForwardControl boolean Does not allow forwardOnKey to reach the end of the file if this value is set to true. A forward command that moves past the end of the file is ignored. The default value is false.
timeLimit integer The number of seconds that the recording will playback when streaming is set to true. Integers entered into this field must be greater than or equal to 1. The default value is 0, meaning that the time is not limited.
waitInitial integer If the initial download is slow and the initial playback cannot start before this number of seconds, waitInitialUrl will start playing.
waitInitialUrl string The file to play for the waitInitial attribute.
waitRepeat integer After waitInitial has elapsed, and if the playback does not start in this number of seconds, waitRepeatUrl will start playing. Repeat every waitRepeat seconds until Play starts.
waitRepeatUrl string The file to play for waitRepeat.

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"
}
Attribute Data Type Description
Digits string If the playback was stopped due to stopOnKey, this is the key that triggered the end of the playback. This value will be empty if the playback ended normally.
PlaybackUrl string The URL of the file that was played.
PlayOffset integer The position of the playback from the beginning of the file when the call ends (either played or skipped to using DTMF controls).

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.

File Noun

Sample Play verb that uses the File noun together with the file_sid parameter to specify the playback file

<Response>
  <Play>
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

The File noun can be nested inside the Play verb. It uses the file_sid attribute of the File object. This attribute specifies the secure ID of the file, which will be played to the calling party. It can be obtained using the Get Files request.

Using the secure ID instead of the link allows the partners to store the files with CarrierX storage and link these files to their FlexML application without the need to set the complete path to the file.

Nesting Rules

PreAnswer

In this example an automatic ‘Sorry, we cannot answer your call right now. Please try again later.’ message will be played to the calling party and then, after a 4-second pause, a pre-recorded message will be repeated three times. Then the call will be rejected.

<Response>
  <PreAnswer>
    <Say>Sorry, we cannot answer your call right now. Please try again later.</Say>
    <Pause length="4"></Pause>
    <Play loop="3">https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3</Play>
  </PreAnswer>
  <Reject reason="busy"></Reject>
</Response>

The PreAnswer verb responds to the incoming call before it is answered. This is a so called early media mode: the media is sent to the calling party before the called party answers the call. This is especially useful when you want to play some custom message (e.g., to warn the calling party about some additional costs) so that they could hang up before the conversation actually starts.

You can also use the PreAnswer to set custom ringtones or to speak specified text dynamically while the call is still in an unanswered state.

Nesting Rules

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

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.

Supported Attributes

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

Attribute Data Type Description
action string The link to another set of FlexML instructions. This is the link that will be requested after the recording has finished. URLs entered into this field can be absolute or relative. The type of request to this URL is set as the method value. Note that if there is no recording or the recording was empty after silence trim (if it was enabled), action does not execute and the next verb following is executed.
backgroundAudioLoop integer This attribute defines how many times backgroundAudioUrl will be repeated.
backgroundAudioUrl string This audio file plays during the recording, but is not recorded. For example, the called party will hear this file, but the recording will only include the audio from the calling party side.
callbackUrl string The URL for the callback. Setting the callbackUrl will enable accessing data about the recording after it has ended.
containerSid string The secure ID of the storage container. If a fileSid is specified, this containerSid should be left blank and will be ignored.
direction string Determines which leg of the call to record. Values accepted in this field are:
  • any to record both calling and called parties;
  • in to record the calling party only;
  • out to record the called party only.
The default value is any, meaning that both legs are recorded.
errorAction string The URL containing the executable FlexML instructions that will be requested if the recording fails.
errorMethod string The method used to request the errorAction URL containing the executable FlexML instructions if the recording fails.
fileFormat string Set as the type of file that will be stored as a recording. Accepted file formats are wav, mp3, and ul. The default value is wav.
fileMode string This value defines whether new recordings will be appended to the storage file, or will overwrite the existing recordings in the file. Values accepted in this field are append and overwrite. The default value is append.
fileSid string The secure ID of the storage file that the recording should be saved to. This is an existing file specified that will override any specified containerSid.
finishOnKey string The key to press to end the recording. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, and *. By default, pressing any valid key will end the recording. The none string value can be passed to disable this feature. Note that multiple values can be passed into a single string. For example, if the 123 string is passed as the finishOnKey value, then pressing 1, 2, or 3 will end the recording.
integerKey1 integer An optional integer identifier that can be used for referential purposes. This value is stored as the integer_key_1 value in the File object.
integerKey2 integer An optional integer identifier that can be used for referential purposes. This value is stored as the integer_key_2 value in the File object.
lifecycleAction string An action that will be performed for the recording file once the lifecycleTtl value is exceeded. The default value is delete.
lifecycleTtl integer The time in seconds before the lifecycleAction is executed for the recording file.
maxLength integer The maximum length of the recording, in seconds. Integers entered into this field must be greater than or equal to 1.
method string The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
playBeep boolean Plays a beep sounds to indicate that a recording has started. If set to false, no beep sound is played. The default value is false.
recordingStatusCallback string The URL where the callback will be sent after the recording has ended.
recordingStatusCallbackMethod string The method, either POST or GET, that the callback to recordingStatusCallback is sent. The default is POST.
recordSession boolean If this attribute is set to true, the whole session will be recorded in the background. The default value is false.
stringKey1 string An optional string identifier that can be used for referential purposes. This value is stored as the string_key_1 value in the File object.
stringKey2 string An optional string identifier that can be used for referential purposes. This value is stored as the string_key_2 value in the File object.
timeout integer The number of seconds of silence allowed before the recording is terminated. Integers entered into this field must be greater than or equal to 1. The default value is 5.
transcribe boolean Transcribes the audio to the human readable text representation. The default value is false. Please note that this is a paid feature. Contact technical support at support@carrierx.com for more information about this.
transcribeCallback string The URL where the callback will be sent after the transcription is finished.
transcribeLowConfidenceWordReplacement string The word or character that will be used to replace the words with low confidence (that was hard to recognize for the system) in the resulting transcription. The default value is _.
transcribeLowConfidenceWordThreshold number The confidence level below which the word is considered unrecognized and is replaced with the transcribeLowConfidenceWordReplacement word/character. Values accepted in this field are numbers between 0 and 1. The default value is 0.01.
transcribeTimeout integer The time in seconds during which the system will wait for the transcription callback. If this time is exceeded and no transcription is ready, the system will send the callback with the timeout status.
trim string Determines whether or not silence is removed from the beginning or ending of a recording. To keep the silence in the recording, set this field to do-not-trim. The default value is trim-silence.

Supported External Storage

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

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.

Amazon Simple Storage Service

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>
Attribute Data Type Description
awsAccessKey required string The access key used to access AWS S3.
awsBucketName required string The bucket name where the recording will be stored.
awsSecretKey required string The secret key used to access AWS S3.

Google Cloud Platform

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>
Attribute Data Type Description
gcpAccessToken string The access token used to access Google Cloud Platform. This attribure is only required if you do not specify gcpRefreshToken, gcpClientId, and gcpClientSecret.
gcpBucketName required string The bucket name where the recording will be stored.
gcpClientId string The client ID used to access Google Cloud Platform. This attribute is only required if you do not specify gcpAccessToken.
gcpClientSecret string The client secret used to access Google Cloud Platform. This attribute is only required if you do not specify gcpAccessToken.
gcpProject required string The project that will be used to store the recording.
gcpRefreshToken string The refresh token used to access Google Cloud Platform. This attribute is only required if you do not specify gcpAccessToken.

Microsoft Azure Blob Storage

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>
Attribute Data Type Description
azureAccountKey string The account key used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify azureSasToken.
azureAccountName required string The account name used to access Microsoft Azure Blob storage.
azureContainerName required string The container name where the recording will be stored.
azureSasToken string The SAS token used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify azureAccountKey.

Callback Returned Data

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

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RecordingDuration": 60,
    "RecordingSid": "ea662226-9f71-44fe-858f-f8b624034974",
    "RecordingUrl": "https://storage.carrierx.com/f/ea662226-9f71-44fe-858f-f8b624034974",
    "To":"15162065337",
    "TranscriptionSid": "cac8582f-db8a-4c4d-82e5-3e8026435a54",
    "TranscriptionStatus": "completed",
    "TranscriptionText": "This is a transcribed recorded call text",
    "TranscriptionUrl": ""
}

The following are additional parameters and values that will be returned in action requests.

Attribute Data Type Description
RecordingDuration integer The length in seconds of the recording.
RecordingFileSid string The secure ID of the recording file. This can be used with the CarrierX Storage API.
RecordingUrl string The URL where the recording is located.
TranscriptionSid string The identifier of the transcription file.
TranscriptionStatus string The status of the transcription.
TranscriptionText string The complete text of the recorded call transcription.
TranscriptionUrl string The publicly accessible URL of the transcription. Currently, this field is a placeholder and not used.

Nesting Rules

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.

Attribute Data Type Description
method string The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.

Nesting Rules

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.

Attribute Data Type Description
reason string The reason for rejecting a call. This internal data is sent to the carrier, which determines the handling behavior. Values accepted in this field are: redirect, forbidden/rejected, not-found, busy-here, bad-gateway, unavailable, busy, decline, does-not-exist, unwanted, and intermediary-rejected. Refer to the table below for the explanation of each reason for rejecting a call. The default value is rejected.

Reject Reasons

Response Code Reject Reason Description
redirect 302 Moved Temporarily The destination has been temporarily moved to another location.
forbidden/rejected 403 Forbidden The destination understood the request, but is refusing to fulfill it.
not-found 404 Not Found The destination could not be found.
busy-here 486 Busy Here The destination is busy at the current location.
bad-gateway 502 Bad Gateway Network is out of order and the call cannot be accepted.
unavailable 503 Service Unavailable Temporary failure.
busy 600 Busy Everywhere All possible destinations are busy.
decline 603 Decline The destination does not wish to participate in the call or cannot do so.
does-not-exist 604 Does Not Exist Anywhere The server has authoritative information that the requested destination does not exist anywhere.
unwanted 607 Unwanted The destination does not want to accept the call from the current calling party. All future attempts from the same source are likely to be similarly rejected.
intermediary-rejected 608 Rejected The intermediary machine or process rejected the call attempt from the calling party. This status code usually informs the calling party that the decision has been made by an analytics engine or some other similar engine. It also allows the call terminator to additionally specify the reason for rejecting the call.

intermediary-rejected Reject Reason

In this example, the call will be rejected and the reject message to the carrier will be intermediary-rejected. My reason for rejecting the call will be returned as the additional message to the calling party as a part of the Call-Info SIP header.

<Response>
  <Reject reason="intermediary-rejected">My reason for rejecting the call</Reject>
</Response>

Sample Call-Info SIP header returned from the above Reject verb with the intermediary-rejected reject reason

Call-Info: "My reason for rejecting the call"

With the intermediary-rejected reject reason, you can additionally return the message to the calling party that will not only state the reject code, but will also explain the reason of the reject. To do this, insert the message text between the start and end Reject tags.

FlexML will return the message text as a part of the Call-Info SIP header.

Nesting Rules

Say

In this example, a thank you message will be read twice to the calling party 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 calling party will hear. Supported attributes can be added to customize the type of voice and the number of repetitions of the message.

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

Attribute Data Type Description
loop integer The amount of times that the message will play. Integers entered into this field must be greater than or equal to 0. Enter 0 to play the message repeatedly until the call is ended. The maximum value accepted in this field is 100. The default value is 1.
loopPause integer The number of seconds between each loop repetition. Integers entered into this field must be greater than or equal to 1. The maximum value accepted in this field is 300. The default value is 0, meaning that there will be no pause between repetitions.
voice string The type of voice that will read the text. Values accepted in this field are man and woman. The default value is man.

Nesting Rules

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

Attribute Data Type Description
action string The link to the set of FlexML instructions that will be requested after the Sms verb has been executed.
from string The phone number that will send the message. The phone number must be in the E.164 format. If no from value is added, this value will default to the phone number that the call is from.
method string The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
to string The phone number that will receive the message. The phone number must be in the E.164 format. If no to value is added, this value will default to the phone number that received the call.

Nesting Rules

Store

In this example, the additional data identified by the key1 and key2 names will be added to the callback returned data. The data will be passed to the URL specified in the Redirect verb together with the other call data.

<Response>
  <Store name="key1">some_data</Store>
  <Store name="key2">some more data</Store>
  <Redirect>http://www.example.com/path/to/handler</Redirect>
</Response>

The Store verb allows the users to store additional data between the requests within the same call without having to pass it using either query string or some other workaround.

Supported Attributes

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

Attribute Data Type Description
name string The name of the data used to identify it within the Callback Returned Data.

Callback Returned 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",
    "Storage_key1": "some_data",
    "Storage_key2": "some more data",
    "To":"15162065337"
}

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

Attribute Data Type Description
Storage_{name} string The name of the data key used to store the data between the requests. It consists of the static Storage_ part and the {name} variable received as the name attribute of the Store verb.

Nesting Rules

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 for more information.

Nesting Rules

API Reference

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

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
}
Attribute Data Type Description
account_sid read only string The account secure ID.
date_created read only string The date and time when the account was created.
error_handler update string This is the way that is used to handle the errors. Values accepted in this field are basic and none. When the value is basic, a recording will play when an app error occurs. If the value is set to none , error handling will defer to the carrier settings. The default value is basic.
login read only string The login username used to access the FlexML endpoint. Each endpoint has a unique login and password.
method update string The HTTP method used to execute the request if no method is assigned in the DID object. This method can be set as either POST or GET. The default value is POST.
name update string The account name. This is a human-readable nickname for the account.
password read only string The password used to access the FlexML endpoint. Each endpoint has a unique login and password. The password field is hidden and not returned in the responses.
url update string The URL where the FlexML instructions are located. To indicate the type of request sent to this URL, set the method field.

Get Accounts

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

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

Response 200 status 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 accounts data for the currently logged-in partner.

GET /accounts

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

Get Account by SID

GET /accounts/{account_sid}
Returns an account, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts/1d4adc32-45d1-4789-9780-928049e2bce1' \
-u '[your_user_name]:[your_password]'

Response 200 status 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.

GET /accounts/{account_sid}

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
account_sid required string The account secure ID.

Update Account

PATCH /accounts/{account_sid}
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/1d4adc32-45d1-4789-9780-928049e2bce1' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"POST", "error_handler": "none"}' \
-u '[your_user_name]:[your_password]'

Response 200 status 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.

PATCH /accounts/{account_sid}
PUT /accounts/{account_sid}

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

Path Arguments
Parameter Data Type Description
account_sid required string The account secure ID.
Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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": "15162065318",
    "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 Data Type Description
account_sid read only string The secure ID of the account to which the call belongs.
attributes create update object Additional attributes that can be used to further customize a call. See the table below for built-in attributes. Custom attributes can also be added to this parameter as key-value pairs.
call_sid read only string The call secure ID.
called_did create update string The call destination phone number. This phone number will appear in the E.164 format.
calling_did create update string The DID that initiates the call. This DID will appear in the E.164 format.
date_created read only string The date and time when the Call object was created.
delay create update integer The number of seconds before the call will execute. The default value is 0, meaning that the call will execute immediately.
method create update string The HTTP method used to execute the request. This method can be set as either POST or GET. The default value is POST.
status_callback_method create update string The HTTP method used to execute the request to the status_callback_url. The default value is POST.
status_callback_url create update string The URL that stores the call data, which can be heard at the end of a call. Set the way that this URL is queried by assigning the status_callback_method value.
url create update string The URL with the FlexML instructions. The request type used to query this URL is the value of method.
Attribute Object

The following are attributes that can be added to the Call object.

Attribute Data Type Description
cnam create update string The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN.
sip_header_* create update string The values in this field will be sent as extra SIP headers, added to the SIP invite. The header name must start with X-.

Create Call

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

Response 200 status 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": "15162065318",
    "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.

/calls
Body Arguments

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

Required fields to create a call are:

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

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

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

Response 200 status 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.

GET /calls

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

GET /calls/{call_sid}
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]'

Response 200 status 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.

GET /calls/{call_sid}

The call_sid must be passed in the path arguments.

This request is enabled for Field Filtering.

Path Arguments
Parameter Data Type Description
call_sid required string The call secure ID.

Update Call

PATCH /calls/{call_sid}
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]'

Response 200 status 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.

PATCH /calls/{call_sid}
PUT /calls/{call_sid}

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

Path Arguments
Parameter Data Type Description
call_sid required string The call secure ID.
Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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

Delete Call

DELETE /calls/{call_sid}
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]'

Response 204 status code with an empty body

This request deletes a call, targeted by secure ID.

DELETE /calls/{call_sid}
Path Arguments
Parameter Data Type Description
call_sid required string The call secure ID.

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": "USA",
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}
Attribute Data Type Description
account_sid read only string The secure ID of the account to which the DID belongs.
country_code read only string The ISO 3166-1 alpha-3 code of the DID.
did_sid read only string The DID secure ID.
in_country_format read only string The DID in a national format.
international_format read only string The DID in an international format.
method update string The HTTP method used to execute the request. Values accepted in this field are POST or GET. The default value is POST.
phonenumber read only string The phone number for the DID in the E.164 format without the + prefix.
status_callback_method update string The method used to request status_callback_url. Values accepted in this field are POST or GET. The default value is POST.
status_callback_url update string If a URL is provided in this field, there will be a message at the end of calls involving this DID that provides information about the call. Assign this URL to obtain call length, etc.
url update string The URL where the instructions are located. If the url is not defined for a specific DID, the url from the Account object will be used.

Get DIDs

GET /dids
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]'

Response 200 status 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": "USA",
            "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
            "in_country_format": "(516) 206-5319",
            "international_format": "+1 516-206-5319",
            "method": "POST",
            "phonenumber": "15162065319",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

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

GET /dids

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

Get DID by SID

GET /dids/{did_sid}
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]'

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

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": "USA",
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

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

GET /dids/{did_sid}

This request is enabled for Field Filtering.

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

Update DID

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

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/dids/d72c0ec3-c21d-4db1-8877-690cb9644fbc' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"GET"}' \
-u '[your_user_name]:[your_password]'

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

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": "USA",
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "method": "GET",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request updates a DID, targeted by secure ID.

PATCH /dids/{did_sid}
PUT /dids/{did_sid}

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

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

JSON representation of the fields and values to be updated.

Fields that can be modified are:

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