FlexML Reference Guide

Getting Started

The CarrierX service offers a hosted FlexML endpoint. This endpoint type enables you to create complex voice workflows by passing simple XML instructions. Using a variety of VERBS, your endpoint can lookup the instructions on your server to play recordings, route calls via DTMF inputs or implement call-flow logic to deliver the call experience you are looking for.

You will need to provision the Application Endpoint type flexml in your account prior to accessing its API Reference Guide.


Quick Start Guide: How to Provision an Application Endpoint

Upon successful provisioning of your Application Endpoint flexml, you will be provided a username and password to access the service. The FlexML API can be accessed from the following base URL:


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

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

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

Markup Language

Your FlexML Endpoint can interpret a set of instructions delivered via a simple markup language using verbs. url parameter and read the instructions provided to understand what to do with the call, such as reject it or play an audio file.

The list of currently supported verbs (i.e. actions) for a call are:

Dial – perform an outbound call to add another participant to the call.
Gather – collect digits (DTMF tones) the caller taps on the keypad.
Hangup – disconnect / hang up the call.
Pause – wait before executing further instructions.
Play – play an audio file for the caller (supported formats: .wav and .mp3).
Redirect – perform a redirect of the call to another number.
Reject – decline the incoming call.

The following sections will dwell deeper on each of the supported verbs together with code samples.

Dial

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

If the dialed number is not reached, or the call is terminated, CarreirX will make a GET or POST request to the ‘action’ URL. The call flow will proceed then with the new FlexML fetched from the ‘action’ URL. The rest of the verbs in the current file will be ignored.

Note: If no ‘action’ URL is defined, the call flow will move to other verbs in the current FlexML.

Supported Attributes

The following attributes can be used to modify the verb

Attribute	Values	Description
action	relative or absolute URL	Link to another FlexML file that the flow will use after the call has been terminated, or the dialed party is not available.
method	GET, POST	Defines whether to request the ‘action’ URL via http GET or POST. The default value is POST.
timeout	integer	Number of seconds to wait for the destination number to answer. The default value is 30.
timeLimit	integer	Number of seconds for the call to last.
hangupOnStar	true / false	Allows to hang up on the dialed number and switch to the next following verbs in the current FlexML. Until then, the verbs will remain blocked.

Example:

<Response>
  <Dial method="get" timeLimit="13" hangupOnStar="true">
    <Number>18888888888</Number>
    <Number>17777777777</Number>
  </Dial>
</Response>

Gather

The GATHER verb collects the digits that a caller enters into the telephone keypad. The entered data is further passed to the ‘action’ URL in an HTTP GET or POST request.

In case of no input, the call will move to the next following verb in the current FlexML.

Supported Attributes

The following attributes can be used to modify the Dial behavior

Attribute	Values	Description
action	relative or absolute URL	Link to another FlexML file that the flow will use after the input has been submitted, or upon expiration of the timeout.
method	GET, POST	Defines whether to request the ‘action’ URL via http GET or POST. The default value is POST.
timeout	integer	Number of seconds to wait for the caller’s next input before moving to the “action” URL request. The default value is 5 seconds.
numDigits	integer >= 1	The expected number of digits to be entered in order to submit data to the 'action' URL.
finishOnKey	0-9, #, *, and '' (the empty string)	Defines the single key upon pressing which the entered data will be submitted. If not specified, the input will be submitted after the timeout is expired. The default value is '#'.

Optionally, the following verbs can be nested within Gather:

Say
Refer to the below example to nest the Say verb into the Gather verb

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

Play
Refer to the below example to nest the Play verb into the Gather verb

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

Hangup

Hangup will finish the call. Unlike the Reject, it will still answer the call and only then hang up. Use the verb Reject if you meant the call to remain unanswered.

<Response>
  <Hangup/>
</Response>

Pause

The verb waits for the defined number of seconds before moving to the next verb.

Supported Attributes

Attribute	Values	Description
length	integer >= 1	Pause duration. The default value is 1 second.

Example:

<Response>
  <Pause length="15"/>
</Response>

Play

Play will play back the file to the caller. The file location is defined in the URL parameter.

Supported Attributes

Use the following attributes to change the verb behavior:

Attribute	Values	Description
forwardOnKey	0-9, #, *, and '' (the empty string)	Used to track forward the recording by pressing one of the keys defined in Values
rewindOnKey	0-9, #, *, and '' (the empty string)	Used to rewind the recording by pressing one of the keys defined in Values
pauseOnKey	0-9, #, *, and '' (the empty string)	Used to pause the playback of the recording by pressing one of the keys defined in Values
stopOnKey	0-9, #, *, and '' (the empty string)	Used to stop the recording by pressing one of the keys defined in Values
restartOnKey	0-9, #, *, and '' (the empty string)	Used to restart the paused playback by pressing one of the keys defined in Values
controlSkip	integer >= 1	Amount of seconds to be skipped
streaming	true / false	Allows to play the stream file defined in the URL parameter. Supported formats: mp3, ogg, wav, aac Protocols: http[s], hls, rtmp Play list: m3u8 ( hls like )
timeLimit	integer >= 1	Number of seconds the recording will play back when streaming=true.
loopPause	integer >= 1	Number of seconds between each repetition
loop	integer >= 1	Number of times the file will be played. The default value is 1. Setting to 0 will make the file play repeatedly until the call is finished.

Note: if ‘streaming’ is defined for the Play verb, all *OnKey attributes are ignored.

Example:

<Response>
  <Play streaming="true" timeLimit="30">
    http://link_to_stream_file
  </Play>
</Response>

SMS

The Sms verb sends an SMS message to a phone number during a phone call.

Supported Attributes

Use the following attributes to change the verb behavior:

Attribute	Values	Description
to	string	Phone number of the message receiver. Must be in E.164 format
from	string	Phone number of the message sender. Must be in E.164 format
action	relative or absolute URL	Link to another FlexML file that the flow will use after Sms verb is executed. Other verbs following the Sms which specifies an 'action' attribute are ignored. If no action is provided, the call flow will transfer to the next coming verb.
method	GET, POST	Defines whether to request the ‘action’ URL via http GET or POST. The default value is POST.

Example:

<Response>
  <Sms to="18083842079">Write your message here.</Sms>
</Response>

Record

The Record verb records the caller's voice and stores it as an audio file in the defined container.

Note: ensure your account has got storage capabilities enabled for you to keep and to access the recorded files. For more information on how to get access to your storage, please contact our customer support service at support@carrierx.com, or call (844) 844-0707 (for US customers) and +15623499000 (for international customers)

Supported Attributes

Use the following attributes to change the verb behavior:

Attribute	Values	Description
action	relative or absolute URL	Link to another FlexML file that the flow will use after the recording is finished.
method	GET, POST	Defines whether to request the ‘action’ URL via http GET or POST. The default value is POST.
timeout	integer >=1	Number of silence seconds to elapse before terminating the recording. 5 sec by default
finishOnKey	1234567890*#	To finish the recording by pressing one of the keys defined in Values. Any digits by default.
maxLength	integer >=1	Defines the maximum length of the recording. The default value is 3600 seconds (1 hour)
playBeep	true, false	Allows toggling between playing a sound before the start of the recording. The default value is ‘true’. If set to 'false', no beep sound will be played.
trim	trim-silence, do-not-trim	Allows to remove the silent seconds at the beginning or ending of the recording. The default value is trim-silence.
containerSid	string	secure ID of the container in the storage
fileSid	string	secure ID of the file in the storage
fileMode	append, overwrite	Allows to define whether the defined file should be updated with the new recordings, or overwritten. Default value is append.

Redirect

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

Supported Attributes

Attribute	Values	Description
method	GET, POST	Defines whether to request the URL via HTTP GET or POST. The default value is POST.

Example:

<Response>
  <Redirect method="POST">http://another_xml.xml</Redirect>
</Response>

Reject

The Reject verb rejects an incoming call.

Supported Attributes

Attribute	Values	Description
reason	rejected, busy	Defines what message to play when the call is rejected.

Note: To ensure the incoming call remain unanswered, put Reject as the first verb in your response.

Say

Say translates the written text to voice the call originator hears after dialing the number.

Use the following attributes when configuring your Say verb. You may define the voice of the speaker (man or woman), and also the number of repetitions.

Supported Attributes

Attribute	Values	Default Values
voice	man, woman	man
loop	integer >= 0	1 0 if unlimited
loopPause	integer >= 1	Number seconds between each repetition.

Example:

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

Partners

Once you have obtained your log in credentials, you will be able to access our web-based API Explorer and grab Curl examples to short-cut your coding. Additionally, your credentials will allow you to immediately access our platform programmatically should you prefer.

We look forward to supporting your understanding of our FlexML API

Get Accounts Matching the Specified Criteria

This call will show data for the currently logged in Account.

METHOD	URL
GET	/accounts

Sample URL


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

Request Parameters

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

Sample Response

 {
  "offset": 0,
  "limit": 10,
  "total": 1,
  "has_more": false,
  "items": [
      {
          "account_sid": "e4d82fab-b613-4c0d-bd40-a9f94e8263c7",
          "login": "PROD_Dec20_flexml_756",
          "name": "N/A",
          "date_created": "2016-12-20T07:23:37.000Z",
          "callback_url": null
      }
  ]
}

Response Parameters

Attribute	Data Type	Description
account_sid `opt`	string	Account secure ID
name `opt`	string	Account name
login	string	Login to the web or WS API
password	string	Password to the web or WS API. `The field is hidden`
date_created `opt`	string	Date and time when the account was created
callback_url `opt`	string	Callback for this account for different events

Get Account by SID

The call will return information for a particular Account whose secure ID is specified to retrieve the data.

METHOD	URL
GET	/accounts/{account_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u : "https://api.carrierx.com/flexml/v1/accounts/e4d82fab-b613-4c0d-bd40-a9f94e8263c7"

Response Parameters

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

Sample Response

 {
  "account_sid": "e4d82fab-b613-4c0d-bd40-a9f94e8263c7",
  "login": "PROD_Dec20_flexml_756",
  "name": "N/A",
  "date_created": "2016-12-20T07:23:37.000Z",
  "callback_url": null
}

Response Parameters

Attribute	Data Type	Description
account_sid `opt`	string	Account secure ID
name `opt`	string	Account name
login	string	Login to the web or WS API
password	string	Password to the web or WS API. `The field is hidden`
date_created `opt`	string	Date and time when the account was created
callback_url `opt`	string	Callback for this account for different events

OAuth

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

Revoke Current OAuth Token

This call will terminate your session.

METHOD	URL
POST	/oauth/logout

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/oauth/logout"

Revoke OAuth Token

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

METHOD	URL
POST	/oauth/revoke/{token}

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/oauth/revoke//8bfd6c6d-6291-488a-bed1-8784c195ce87"

Parameters

Parameter	Data Type	Description
token `req`	string	Access token

Get OAuth Bearer Token

This call generates the token for a partner upon request.

METHOD	URL
POST	/oauth/token

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password]  "https://api.carrierx.com/flexml/v1/oauth/token?grant_type=password&client_id=carrierx&client_secret=50339091-14fe-442c-bbcb-83b674dbf90c&username=carrierx&password=carrierx_pwd&scope=trust"

Parameters

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

Sample Response

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

Attributes

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

Get All Active OAuth Bearer Tokens for the Partner

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

METHOD	URL
GET	/oauth/token

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/oauth/tokens"

Sample Response

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

Attributes

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

Get the Currently Logged in Partner

The call will return the currently logged in partner.

METHOD	URL
GET	/oauth/whoami

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name];[your_password] "https://api.carrierx.com/flexml/v1/oauth/whoami"

Sample Response

 {
  "name": "N/A",
  "login": "twl_Dec15_flexml_389",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "date_created": "2016-12-15T07:20:25.000Z"
}

Attributes

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

Calls

FlexML is a custom endpoint that runs a subset of CarrierX language markup. Calls initiated via the API and the Dial command run as the CarrierX partner associated with the account.

Get Calls Matching the Specified Criteria

This method will obtain the list of existing call objects scheduled for some time in the future; i. e. the “delay” parameter has been set to some value in seconds that should elapse before the call is performed. The delay parameter can be set up at the call creation step and updated later on with PATCH or PUT requests. By default, the “delay” parameter is set to 0, meaning the call will be initiated right after the request has been sent.

METHOD	URL
GET	/calls

Sample URL


curl -X GET --header "Accept: application/json" -u "[YOUR USERNAME]:[YOUR PASSWORD]"  "https://api.carrierx.com/flexml/v1/calls?offset=0&limit=10"

Response Parameters

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

Sample Response

 {
  "offset": 0,
  "limit": 10,
  "total": 1,
  "has_more": false,
  "items": [
      {
          "call_sid": "d1a03f86-1415-495d-9f92-1eaca05c84ef",
          "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
          "date_created": "2016-12-15T10:39:38.000Z",
          "delay": 456446023,
          "attributes": {},
          "calling_did": "12092551253",
          "called_did": "156156156",
          "url": null,
          "method": "POST"
      }
  ]
}

Response Parameters

Attribute	Data Type	Description
call_sid `opt`	string	Call secure ID
account_sid `opt`	string	Secure ID of the Account which call belongs to
date_created `opt`	string	Date when the call was created
delay `opt`	integer	Delay for the call in seconds
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
calling_did `opt`	string	DID which initiates the call in E.164 format
called_did	string	Call destination DID in E.164 format
url	string	URL the instructions are located at
attributes	string	Additional attributes for the Call

Create a Call

This call creates a new call object.

The mandatory fields are “calling_did” and “called_did”. The “calling_did” should be set to the one of the available did numbers value. If you want to schedule the call for some time in the future, set the “delay” parameter to the amount of seconds, upon expiration of which the call will be initiated

METHOD	URL
POST	/calls

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{"calling_did":"12092551251", "called_did":"15112341211", "url":""}" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/calls"

Request Parameters

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

Sample Response (type = flexml)

{
  "call_sid": "89cd0adc-5686-470a-8340-bf51138e67dd",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "date_created": "2016-12-15T14:17:36.732Z",
  "delay": 0,
  "attributes": {},
  "calling_did": "12092551251",
  "called_did": "15112341211",
  "url": null,
  "method": "POST"
}

Response Parameters

Attribute	Data Type	Description
call_sid `opt`	string	Call secure ID
account_sid `opt`	string	Secure ID of the Account which call belongs to
date_created `opt`	string	Date when the call was created
delay `opt`	integer	Delay for the call in seconds
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
calling_did `opt`	string	DID which initiates the call in E.164 format
called_did	string	Call destination DID in E.164 format
url	string	URL the instructions are located at
attributes	string	Additional attributes for the Call

Remove Call

This request will delete the call of the specified secure ID. In case of success, the existing call will be removed. If the call which is specified has not been found, error 404 will be returned.

METHOD	URL
DELETE	/calls/{call_sid}/

Sample URL


curl -X DELETE --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/calls/d1a03f86-1415-495d-9f92-1eaca05c84ef"

Response Parameters

Parameter	Data Type	Description
call_sid `req`	string	Call secure ID.

Get Call by SID

This call will return configured call parameters in JSON format for the secure ID specified.

METHOD	URL
GET	/calls/{call_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/calls/d1a03f86-1415-495d-9f92-1eaca05c84ef"

Request Parameters

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

Sample Response

 {
  "call_sid": "d1a03f86-1415-495d-9f92-1eaca05c84ef",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "date_created": "2016-12-15T10:39:38.000Z",
  "delay": 456441881,
  "attributes": {},
  "calling_did": "12092551253",
  "called_did": "156156156",
  "url": null,
  "method": "POST"
}

Response Parameters

Attribute	Data Type	Description
call_sid `opt`	string	Call secure ID
account_sid `opt`	string	Secure ID of the Account which call belongs to
date_created `opt`	string	Date when the call was created
delay `opt`	integer	Delay for the call in seconds
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
calling_did `opt`	string	DID which initiates the call in E.164 format
called_did	string	Call destination DID in E.164 format
url	string	URL the instructions are located at
attributes	string	Additional attributes for the Call

Patch Call

This call will patch the existing call instance. Use this call to update one or several attribute values of a specified call. Note: only values of the attributes specified in the call will be updated. The rest will preserve their original value. You will be able to patch only those calls which “delay” attribute value is greater than 0.

METHOD	URL
PATCH	/calls/{call_sid}

Sample URL


curl -X PATCH --header "Content-Type: application/json" --header "Accept: application/json" -d "{"delay":"7878787”}" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/calls/592210fa-8126-4255-bc77-c8dedb6af834"

Request Parameters

Parameter	Data Type	Description
call_sid `req`	string	Call secure ID
body `req`	...	Call body

Sample Response

{
  "call_sid": "592210fa-8126-4255-bc77-c8dedb6af834",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "date_created": "2017-02-02T10:29:03.000Z",
  "delay": 7878787,
  "attributes": {},
  "calling_did": "12092551251",
  "called_did": "1234565411",
  "url": null,
  "method": "POST"
}

Response Parameters

Attribute	Data Type	Description
call_sid `opt`	string	Call secure ID
account_sid `opt`	string	Secure ID of the Account which call belongs to
date_created `opt`	string	Date when the call was created
delay `opt`	integer	Delay for the call in seconds
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
calling_did `opt`	string	DID which initiates the call in E.164 format
called_did	string	Call destination DID in E.164 format
url	string	URL the instructions are located at
attributes	string	Additional attributes for the Call

Update an Existing Call

This call will update a single call instance. This call can be used both to remove and to add values. Note: You will be able to patch only those calls which “delay” attribute value is greater than 0.

METHOD	URL
PUT	/calls/{call_sid}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d " {"call_sid": "592210fa-8126-4255-bc77-c8dedb6af834", "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf", "date_created": "2017-02-02T10:29:03.000Z", "delay": 7874524, "attributes": {}, "calling_did": "12092551251", "called_did": "1234565411", "url": null, "method": "POST" }" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/calls/592210fa-8126-4255-bc77-c8dedb6af834"

Request Parameters

Parameter	Data Type	Description
call_sid `req`	string	Call secure ID
body `req`	...	Call body

Sample Response

 {
  "call_sid": "592210fa-8126-4255-bc77-c8dedb6af834",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "date_created": "2017-02-02T10:29:03.000Z",
  "delay": 7878787,
  "attributes": {},
  "calling_did": "12092551251",
  "called_did": "1234565411",
  "url": null,
  "method": "POST"
}

Response Parameters

Attribute	Data Type	Description
call_sid `opt`	string	Call secure ID
account_sid `opt`	string	Secure ID of the Account which call belongs to
date_created `opt`	string	Date when the call was created
delay `opt`	integer	Delay for the call in seconds
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
calling_did `opt`	string	DID which initiates the call in E.164 format
called_did	string	Call destination DID in E.164 format
url	string	URL the instructions are located at
attributes	string	Additional attributes for the Call

CallBacks

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

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

Sample JSON Response

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

Attribute	Data Type	Description
price	string	The associated price
message_segments	integer	Number of segments in the message
mnc	string	Mobile network code
status	string	Status of the message created queued sending sent receiving

DIDs

Get DIDs Matching the Specified Criteria

Shows the list of DID numbers rented with CarrierX. If no filter is specified, the number of displayed items will be limited by the ‘limit’/’offset” values only. If the number of items exceeds the “limit” value, the ‘has_more’: in the response is set to “true”.

METHOD	URL
GET	/dids

Sample URL


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

Request Parameters

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

Sample Response

          {
          "phonenumber": "12092551251",
          "did_sid": "70999383-9162-405f-8f62-a550a416ee21",
          "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
          "url": null,
          "method": "POST",
          "country_code": null,
          "in_country_format": null,
          "international_format": null
      }

Response Parameters

Attribute	Data Type	Description
phonenumber	string	Phone number for this DID in E.164 format
did_sid	string	DID secure ID
account_sid	string	Secure ID of the Account which DID belongs to
country_code	string	ISO 3166-1 alpha-3 code of this DID, given automatically

in_country_format	string	DID in national format
url	string	URL the instructions are located at
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
international_format	string	DID in international format

Get DID by SID

This call will allow you to obtain detailed information for the selected DID associated to a specific SID.

METHOD	URL
GET	/dids/{did_sid}

Sample URL


curl -X GET --header "Accept: application/json" -u [your_user_name]:[your_password] "https://api.carrierx.com/flexml/v1/dids/70999383-9162-405f-8f62-a550a416ee21"

Request Parameters

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

Sample Response

 {
  "phonenumber": "12092551251",
  "did_sid": "70999383-9162-405f-8f62-a550a416ee21",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "url": null,
  "method": "POST",
  "country_code": null,
  "in_country_format": null,
  "international_format": null
}

Response Parameters

Attribute	Data Type	Description
phonenumber	string	Phone number for this DID in E.164 format
did_sid	string	DID secure ID
account_sid	string	Secure ID of the Account which DID belongs to
country_code	string	ISO 3166-1 alpha-3 code of this DID, given automatically

in_country_format	string	DID in national format
url	string	URL the instructions are located at
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
international_format	string	DID in international format

Patch DID

This call will allow you to one or several parameters of a single call which secure ID is specified. Note: only parameters that have been send in the request will be processed. Thre rest will remain unchanged.

METHOD	URL
PATCH	/dids/{did_sid}

Sample URL


curl -X PATCH --header "Content-Type: application/json" --header "Accept: application/json" -d "{"method":"GET"}" -u : "https://api.carrierx.com/flexml/v1/dids/70999383-9162-405f-8f62-a550a416ee21"

Request Parameters

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

Example Response

 {
  "phonenumber": "12092551251",
  "did_sid": "70999383-9162-405f-8f62-a550a416ee21",
  "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf",
  "url": null,
  "method": "GET",
  "country_code": null,
  "in_country_format": null,
  "international_format": null
}

Response Parameters

Attribute	Data Type	Description
phonenumber	string	Phone number for this DID in E.164 format
did_sid	string	DID secure ID
account_sid	string	Secure ID of the Account which DID belongs to
country_code	string	ISO 3166-1 alpha-3 code of this DID, given automatically

in_country_format	string	DID in national format
url	string	URL the instructions are located at
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
international_format	string	DID in international format

Update DID

This call will allow you change several call parameters at a time. For the call to succeed, make sure you input the full body of the DID object

METHOD	URL
PUT	/dids/{did_sid}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{ "phonenumber": "12092551251", "did_sid": "70999383-9162-405f-8f62-a550a416ee21", "account_sid": "c0becaae-ca1d-4ff8-8187-0ad67466ffbf", "url": null, "method": "GET", "country_code": null, "in_country_format": null, "international_format": null }" -u : "https://api.carrierx.com/flexml/v1/dids/70999383-9162-405f-8f62-a550a416ee21"

Request Parameters

Parameter	Data Type	Description
did_sid `req`	string	DID secure ID
body	...	Body of the DID to be updated

Sample Response

 {
  "status": 200,
  "body": {
      "phonenumber": "15162065030",
      "details": [],
      "did_sid": "8aef5616-c28f-4b67-874c-e7082a01656b",
      "account_sid": "c79722ff-2472-47a0-abbc-11ba04ca7a15",
      "country_code": "USA",
      "in_country_format": "(516) 206-5030",
      "international_format": "+1 516-206-5030"
  }
}

Response Parameters

Attribute	Data Type	Description
phonenumber	string	Phone number for this DID in E.164 format
did_sid	string	DID secure ID
account_sid	string	Secure ID of the Account which DID belongs to
country_code	string	ISO 3166-1 alpha-3 code of this DID, given automatically

in_country_format	string	DID in national format
url	string	URL the instructions are located at
method	string	HTTP Method to add the instructions = ['GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE', 'TRACE']
international_format	string	DID in international format

Countries

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

Get Countries Matching the Specified Criteria

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

METHOD	URL
GET	/countries

Sample URL


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

Response Parameters

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

Sample Response

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

Response Parameters

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

Get Country by ISO 3166-1 alpha-3 code

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

METHOD	URL
GET	/countries/{country_code}

Sample URL


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

Response Parameters

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

Sample Response

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

Response Parameters

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

System Codes

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

Success Response

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

Error Response

Response Code	Text	Description
401	Unauthorized	The request requires user authentication.
403	Forbidden	The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
400	Bad request	The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
404	Not Found	The requested resource was not found on the server.
500	Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.