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.

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.