FlexML API Reference Guide




Introduction

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







Using the REST API

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

Credentials

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

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

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


Sample Curl Command

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

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

Sample JSON Response

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

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

Requests

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

The FlexML API has the following base URL:

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

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

Responses

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

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

Pagination

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

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

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

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

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


Sample Curl Command

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

Sample JSON Response

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

Pagination Quick Reference

Parameter Data Type Description
filter optional string Use the filter operators to find records according to specific criteria. Please reference the Relational Operator Quick Reference table above in this section for specific definitions and examples.
offset optional integer The amount of items skipped in the response. 0 is the default value. This parameter and value are added to the query URL.
limit optional integer The number of items to be shown in the response. The value entered should not exceed 1000 . 10 is the default value. This parameter and value are added to the query URL.
order optional string The name of the field to be ordered followed by the order of the response data, either asc or desc . The field to be ordered is listed first, followed by the order value. For example: binding_sid desc . asc is the default order. This parameter and values are added to the query URL.


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


Relational Operator Quick Reference

Operator Definition Example
eq equal to. This search looks for exactly the value entered. In the example, results will have the exact value "my_mediator" for the name field. name eq "my_mediator"
ne not equal to. This search returns records that do not include the value "my_mediator" for the name field. name ne "my_mediator"
gt greater than. This search returns records where the value is exceeded for the field listed. For example, records are returned where the value of maximum_ttl is greater than 40000 . maximum_ttl gt 40000
ge greater than or equal to. This search returns records where the value is greater than or equal to the field listed. For example, records are returned where the value of wait_origination_did_ttl is greater than or equal to 70000 . wait_origination_did_ttl ge 70000
lt less than. This search returns records where the value is less than the field listed. For example, records are returned where maximum_ttl is less than 10000 . maximum_ttl lt 10000
le less than or equal to. This search returns records where the value is less than or equal to the field listed. For example, records are returned where wait_origination_did_ttl is less than or equal to 90000 . wait_origination_did_ttl le 90000
like contains the value indicated in the string passed. % can be added anywhere as part of the string to indicate that there can exist text before or after the string parts. In the example, the command looks for a name starting with "Account". This form of search is case sensitive. Note that this method of search will also work: name like "A%t" , and this search will yield records with name values beginning with A and ending in t . name like "Account%"
ilike same functionality as like but case insensitive. name like "AccOUnt%"
in the current value of the specified field must be contained within the specified list. The following example will return records that have a status value of either "active" or "suspended" . status in ("active", "suspended")

Field Filtering

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

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

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


Sample Curl Command

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

Field Filtering Quick Reference

Parameter Data Type Description
include_fields optional string The comma separated list of fields to be included in the response. The fields depend on the object. See the Object Reference section for that object to see which fields return.
exclude_fields optional string The comma separated list of fields to be excluded from the response. The fields depend on the object. See the Object Reference 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.

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 .


Sample JSON Response

{
  "AccountSid":"",
  "OriginalTo":"15162065337",
  "Direction":"outbound-api",
  "OriginalForm":"15162065338",
  "CallStatus":"",
  "ApiVersion":"2.0",
  "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
  "To":"15162065337",
  "CallerName":"",
  "From":"15162065338"
}

Request Data

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

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 caller.
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 occured.
Direction string Denotes whether the call was inbound or outbound.
From string The calling party phone number, in E.164 format.
OriginalFrom string The calling party phone number in 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 raw format, received directly from the carrier. Note that in development, To will generally be used.
To string The phone number that is dialed, in E.164 format.

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 Gather and the Record sections for additional data returned when using those verbs.

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

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

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

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.

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

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.
RequestMethod string The type of request made to the RequestUrl , either POST or GET .
RequestUrl URL The initial URL to which the request was made, as set in the Call object or DID object.






Markup Language

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


Dial

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

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

Supported Attributes

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

Attribute Data Type Description
action URL 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.
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 .
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 .
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.

Sample FlexML

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

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

Gather

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


Supported Attributes

Attribute Data Type Description
action URL 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 that 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 , # , * . 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 caller’s next input before moving to the action URL request. The default value is 5 .

Sample FlexML

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

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

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

Say

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

Play

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

Request Data

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

Attribute Data Type Description
digits integer The digits entered via DTMF.

Hangup

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

Sample FlexML

<Response>
  <Hangup/>
</Response>

Override

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


Supported Attributes

Parameter Data Type Description
statusCallbackUrl URL The URL to override the status_callback_url value.
statusCallbackMethod string The method to override the status_callback_method value. The default value is POST .

Sample FlexML

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

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


Pause

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


Supported Attributes

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 .

Sample FlexML

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

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

Play

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

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


Supported Attributes

Parameter Data Type Description
action URL The URL containing the executable FlexML instructions that will be requested after the Play file ends.
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 is 60 .
errorAction URL 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.
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 , # , *
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 default value is 1 . The maximum value accepted in this field is 100 .
loopPause integer The number of seconds between each repetition. Integers entered into this field must be greater than or equal to 1 . The default value is 0 , meaning that there will be no pause between repetitions. The maximum value is 300 .
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 .
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 , # , *
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 , # , *
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 , # , *
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 , # , *
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 , # , *
stopOnKey string Used to stop the recording by pressing one of the keys. Values accepted in this field are: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , # , *
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 . The default value is false .

See the table below for information about supported file formats and protocols.
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.

Sample FlexML

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

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

Supported File Formats

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

Supported File Format
aac
al/alaw
flac
g722
m3u8
mp3
mp4/mp4a
ogg
ul/ulaw
wav

Supported Protocols

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

Supported Protocol
hls
http and https
rtmp

Record

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


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


Supported Attributes

Attribute Data Type Description
action URL 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.
callbackUrl URL 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. Accepted values in this field are in to record the calling party and out to record the called party . If the direction attribute is not included, both legs will be recorded.
errorAction URL 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. The values accepted into 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 , # , * . By default, pressing any valid key will end the recording. The string value none can be passed to disable this feature.

Note that multiple values can be passed into a single string. For example, if the string 123 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.
maxLength integer The maximum length of the recording, in seconds. Integers entered into this field must be greater than or equal to 1 . The default value is 3600 .
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. The default value is true . If set to false , no beep sound is played.
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 .
trim string Removes silence at the beginning or ending of a recording. The default value is trim-silence . To keep the silence in the recording, set this field to do-not-trim .
recordSession boolean Set to true to record the whole session in the background.
stringKey1 string An optional integer 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 integer identifier that can be used for referential purposes. This value is stored as the string_key_2 value in the file object.

Sample FlexML

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

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

Callback Returned Data

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

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 URL The URL where the recording is located.

Redirect

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


Supported Attributes

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

Sample FlexML

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

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

Reject

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

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. The values accepted in this field are rejected and busy . The default value is rejected .

Sample FlexML

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

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

Say

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

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

Supported Attributes

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 default value is 1 . The maximum value accepted in this field is 100 .
loopPause integer The number of seconds between each loop repetition. Integers entered into this field must be greater than or equal to 1 . The default value is 0 , meaning that there will be no pause between repetitions. The maximum value is 300 .
voice string The type of voice that will read the text. The values accepted in this field are man and woman . The default value is man .

Sample FlexML

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

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

Sms

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

Supported Attributes

Attribute Data Type Description
action URL 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 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 E.164 format. If no to value is added, this value will default to the phone number that received the call.

Sample FlexML

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

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







Accounts

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

Account Object Reference

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.


Field Data Type Description
account_sid string The account secure ID.
date_created string The date and time when the account was created.
error_handler string This is the way that errors will be handled. The values accepted for 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 string The login username used to access the FlexML endpoint. Each endpoint has a unique login and password.
method 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 string The account name. This is a human-readable nickname for the account.
url URL The URL where the FlexML instructions are located. To indicate the type of request sent to this URL, set the method field.

Get Accounts Matching the Specified Criteria

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

Method URL
GET /accounts

Sample Curl Command

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

Sample JSON Response

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

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


Get Account by SID

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

Method URL
GET /accounts/{account_sid}

Path Arguments

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

Sample Curl Command

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

Sample JSON Response

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

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

Update Account

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

Method URL
PATCH /accounts/{account_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The account attributes to be updated. To view the fields that appear in the Account object, see the Account Object Reference . Fields that can be changed are:
  • error_handler
  • method
  • url

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.


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

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

Method URL
PUT /accounts/{account_sid}

Path Arguments

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

Body Arguments

Parameter Data Type Description
body required object The entire Account object with any updated values. To view the fields that appear in the Account object, see the Account Object Reference . Fields that can be changed are:
  • error_handler
  • method
  • url

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.






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 Reference

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 .

Field Data Type Description
call_sid string The call secure ID.
account_sid string The secure ID of the account to which the call belongs.
attributes string Additional attributes that can be used to further customize a call. See the chart below for built-in attributes. Custom attributes can also be added as values to this parameter.
called_did string The call destination phone number. This phone number will appear in E.164 format.
calling_did string The DID that initiates the call. This DID will appear in E.164 format.
date_created string The date that the Call object was created.
delay integer The number of seconds before the call will execute. The default value is 0 , meaning that the call will execute immediately.
method 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 string The HTTP method used to execute the request to the status_callback_url . The default value is POST .
status_callback_url URL 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 setting the status_callback_method value.
url URL The URL with the FlexML instructions. The request type used to query this URL is the value of method .

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

Parameter Data Type Description
cnam string The CNAM for outbound calls. Note that this may not be preserved for calls terminated through the PSTN.
sip_header_* 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

This request creates a new Call object. The required fields for this request are calling_did and called_did . The calling_did should be one of the DIDs assigned to the FlexML endpoint.

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

Method URL
POST /calls

Body Arguments

Data Type Description
object The parameters and values of the Call object to be created. Required fields to create a Call object are calling_did and called_did . Refer to the Call Object Reference for a list of all fields that appear in the Call object.

Sample Curl Command

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

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Call object . Below are some of the common errors that arise when creating a new call. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.
400 Object validation error Ensure that the calling_did exists and was input correctly into the request.


Get Calls Matching the Specified Criteria

This request will return a list of Call objects scheduled for some time in the future. All Call objects that are returned will have a delay parameter of more than 0 . By default, the delay parameter is set to 0 , so calls will be executed immediately after they are created.

This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /calls

Sample Curl Command

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

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the Call object . Below are some of the common errors that arise when getting a Call object. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.
400 Object validation error Ensure that the calling_did exists and was input correctly into the request.

Get Call by SID

This request will return the Call object associated with a specific call secure ID. This request is enabled for Field Filtering .

Method URL
GET /calls/{call_sid}

Path Arguments

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

Sample Curl Command

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

Sample JSON Response

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

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


Update Call

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

Method URL
PATCH /calls/{call_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The call attributes to be updated. To view the fields that appear in the Call object, see the Call Object Reference . Fields that can be changed are:
  • attributes
  • called_did
  • calling_did
  • delay
  • method
  • status_callback_method
  • status_callback_url
  • url

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.


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

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

Method URL
PUT /calls/{call_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire Call object with any values to be updated. To view the fields that appear in the Call object, see the Call Object Reference . Fields that can be changed are:
  • attributes
  • called_did
  • calling_did
  • delay
  • method
  • status_callback_method
  • status_callback_url
  • url

Sample Curl Command

curl -X PUT \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-H 'Content-Type: application/json' \
--data-binary '{"call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df", "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1", "date_created": "2018-10-16T21:56:49.000Z", "delay": 1000, "attributes": {}, "calling_did": "15162065319", "called_did": "15162065318", "url": null, "status_callback_method":"POST", "status_callback_url": null, "method": "POST" }' \
-u '[your_user_name]:[your_password]'

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified                              Ensure that the parameter is spelled correctly and has been properly added to the URL.

Delete Call

This request will delete the Call object associated with the specified call secure ID.

Method URL
DELETE /calls/{call_sid}

Path Arguments

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

Sample Curl Command

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

A successful request will return a 200 response code with an empty body. Refer to the HTTP Status Codes section errors that can occur when making this call.







DIDs

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

DID Object Reference

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


Field Data Type Description
account_sid string The secure ID of the account to which the DID belongs.
country_code string The ISO 3166-1 alpha-3 code of the DID. This number is automatically assigned.
did_sid string The DID secure ID.
in_country_format string The DID in national format.
international_format string The DID in international format.
method string The HTTP method used to execute the request. Values accepted in this field are POST or GET . The default value is POST .
phonenumber string The phone number for the DID in E.164 format without the + prefix.
status_callback_method 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 URL 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 URL The URL where the instructions are located. If the url is not defined for a specific DID, the account url will be used.

Get DIDs Matching the Specified Criteria

This request returns a list of DIDs associated with a FlexML Application Endpoint. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.

Method URL
GET /dids

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.

Get DID by SID

This request will return detailed information for a DID associated with a specific secure ID. The secure ID is passed in the query URL. This request is enabled for Field Filtering .

Method URL
GET /dids/{did_sid}

Path Arguments

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

Sample Curl Command

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

Sample JSON Response

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

A successful request will return a 200 response code with a serialized copy of the DID object . Below is a common error that arises when retrieving DID data by a secure ID. Refer to the HTTP Status Codes section for additional errors.

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.

Update DID

A DID can be updated using PATCH and PUT requests. A PATCH request requires that the call secure ID is passed in the query URL, and the parameters to be updated is passed in the request body. A PUT request requires the call secure ID passed in the query URL, as well as the entire Call object passed in the query body.

Method URL
PATCH /dids/{did_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The DID attributes to be updated. To view the fields that appear in the DID object, see the DID Object Reference . Fields that can be changed are:
  • account_sid
  • did_sid
  • method
  • status_callback_method
  • status_callback_url
  • url

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.


Use a PUT request to update the entire DID object. The DID secure ID is passed in the query URL, and the body object is passed in the request body.

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

Method URL
PUT /dids/{did_sid}

Path Arguments

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

Body Arguments

Data Type Description
object The entire DID object with any values to be updated. To view the fields that appear in the DID object, see the DID Object Reference . Fields that can be changed are:
  • account_sid
  • did_sid
  • method
  • status_callback_method
  • status_callback_url
  • url

Sample Curl Command

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

Sample JSON Response

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

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

Response Code Message Description
400 Invalid field specified Ensure that the parameter is spelled correctly and has been properly added to the URL.






HTTP Status Codes

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


Success Response

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

Error Responses

Response Code Message Description
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 Unauthorized The request requires user authentication.
401 Bad credentials The request requires correct 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 Not Found The requested resource was not found on the server.
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.
415 Unsupported media type Ensure that the header includes support for the content type JSON.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.