Core Concepts

This section outlines core concepts having to do with the Core API.

Batch Operations

The Batch API allows you to create, update, and delete tasks. Tasks are bulk operations that modify one or more phonenumber, prefix or file. When you create a batch task, you will have the option to review the items if you set the review field to boolean true value. In this case, your returned JSON status will be pending_review.

If the changes look correct, you can make a PATCH or PUT request to change the status from pending_review to approved. If the items look incorrect, the batch request can be prevented from proceeding by changing the status to cancelled.

tip

Refer to the Batch section of the API for comprehensive information about each of the request types and corresponding returned data.

Callbacks

The CarrierX API enables callbacks to be sent to a URL. The callbacks are triggered when a specific action occurs, such as when either sending or receiving an SMS, calling into a conference, etc. The callback data will be the object that was affected. For example, if an SMS was sent to or from a phone number associated with a callback URL, the callback will be the SMS object.

Callbacks are assigned on either the DID object or the Partner object. If a callback URL is assigned on both the DID object level and the Partner object level, the DID object callback URL will override the Partner object callback URL.

On the Partner object, you can set the following callbacks

for SMS activity use the sms field in the callbacks object;
for the mediator endpoints activity use the app_mediator field;
for the conference endpoints activity use the app_conference_call and app_conference_meeting fields.
to get a callback confirming that a DID from an external provider has been rented successfully, use the phonenumber_order field.

On the DID object, set the value of the callback_url field for the callbacks related to SMS activity.

sms and callback_url Callback

The system sends sms and callback_url callbacks when an action related to an SMS event occurs.

Attribute	Data Type	Description
date_changed	string	The date and time when the message was last changed.
date_created	string	The date and time when the system created the message object.
date_status_changed	string	The date and time when the system changed the message status.
direction	string	The message direction.
from	string	The phone number which was used to send the message. Note, that legacy users may still see the old naming instead (`from_did`).
group_recipients	array	The list of phone numbers that an inbound or outbound `mms` group message is delivered to, in E.164 format
mcc	integer	The mobile country code that was used by the operator when sending the message.
media_urls	array	The list of URLs for media resources, if type of message is `mms`.
message	string	The message text. It can be empty when sending multimedia messages (MMS) or contain some text which was sent to the receiving party.
message_segments	integer	The number of segments which the message contains.
message_sid	string	The secure ID of the message which the system uses to identify the message among other messages.
mnc	integer	The mobile network code that was used by the operator when sending the message.
partner_sid	string	The secure ID of the partner associated with the message.
price	number	The message price. It is calculated as (the rate for the message) × (the number of the message segments).
status	string	The status of the message at the moment when the system sent the callback.
to	string	The phone number which was used to receive the message. Note, that legacy users may still see the old naming instead (`to_did`).
type	string	The type of message. Values returned in this field are `mms` and `sms`.
user_data	string	Some additional user-defined data added to the message.

A sample callback response. Refer to the SMS object for more information about each attribute and value.

{
    "date_changed":"2023-09-04T17:37:38.852Z",
    "date_created":"2023-09-04T17:37:36.123Z",
    "date_status_changed":"2023-09-04T17:37:00.000Z",
    "direction":"outbound",
    "from": "15162065319",
    "group_recipients":[],
    "mcc":250,
    "media_urls":[],
    "message": "This is a test inbound message delivered by CarrierX",
    "message_segments": 1,
    "message_sid": "e405fa47-48f5-4dc5-bbba-77231587188e",
    "mnc": null,
    "partner_sid": "QLJ79xlC2vP-UEx3hS0R4rldas8.G1UB",
    "price": "1",
    "status": "received",
    "to": "15162065318",
    "type":"sms",
    "user_data":null}
}

tip

Refer to our Set up SMS Callbacks Using CarrierX Portal quick start guide for more information about the SMS/MMS callbacks and how you can set them using CarrierX portal.

app_mediator Callback

The app_mediator callback is triggered when a call is made to a Mediator binding or from a Mediator dialout.

Attribute	Data Type	Description
attributes	object	The mediator attributes.
date_insert	string	The date and time when the Call Detail Record was processed and added to the database.
date_start	string	The date and time when the call started.
date_stop	string	The date and time when the call stopped.
date_talk	string	The date and time when the call is answered.
direction	string	The direction of the call, either `inbound` or `outbound`.
dr_sid	string	The secure ID of the record.
dtmf	string	The DTMF sequence of the binding.
duration	integer	The duration of the call.
endpoint_sid	string	The endpoint secure ID.
endpoint_type	string	The type of endpoint that triggered the callback.
event_type	string	The event type.
number_dst	string	The destination phone number.
number_redirect	string	The redirect phone number.
number_src	string	The source phone number.
partner_sid	string	The partner secure ID.
reference_sid	string	The `binding_sid` or the `dialout_sid` that was matched for the call.
type	string	The endpoint type.
version	integer	The API version.

A sample app_mediator callback response:

{
    "attributes":{},
    "date_insert":"2019-01-25T18:12:10.770Z",
    "date_start":"2019-01-25T18:08:23.000Z",
    "date_stop":"2019-01-25T18:09:08.000Z",
    "date_talk":"2019-01-25T18:08:44.000Z",
    "direction":"inbound",
    "dr_sid":"2a217f8d-df41-4e3d-bece-c72eaa2a8e2a",
    "dtmf":null,
    "duration":45,
    "endpoint_sid":"632ec9ba-5bef-4ed3-a36d-56feec8ffd41",
    "endpoint_type":"mediator",
    "event_type":"binding",
    "number_dst":"15162065344",
    "number_redirect":"15162065346",
    "number_src":"15162065345",
    "partner_sid":"ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "reference_sid":"05561bef-ce48-4823-a847-bf10f7837a42",
    "type":"mediator",
    "version":2
}

tip

Refer to our Set up Mediator Callbacks Using CarrierX Portal quick start guide for more information about the Mediator endpoint callbacks and how you can set them using CarrierX portal.

app_conference_call Callback

The app_conference_call callback is triggered when the calling party calls a phone number associated with the Conference endpoint.

Attribute	Data Type	Description
address_dst	string	The fully qualified address of the called party which includes the SIP information with special characters formatted.
address_src	string	The fully qualified address of the calling party which includes the SIP information with special characters formatted.
bridge	string	The name of the bridge which handled the call.
call_sid	string	The secure ID of the call which the system uses to identify it among other calls.
custom_call_type	string	The special field used to identify the origin of the call.
custom_name	string	The custom name for the calling party set by the software used, web, or IVR with special characters formatted.
date_disconnected	string	The date and time when the call was disconnected from the meeting.
date_insert	string	The date and time when the detail record about the call was inserted into the database.
date_join	string	The date and time when the calling party joined the meeting.
date_start	string	The date and time when the call started.
date_stop	string	The date and time when the call ended.
direction	string	The call direction, either `inbound` or `outbound`.
disconnect_cause	integer	The numeric SIP code used to describe the reason to drop the call.
disconnect_originator	string	The initiator of the disconnection.
disconnect_reason	string	The detailed descriptive information about the reason to drop the call.
duration	number	The total call duration, specified in seconds.
duration_meeting	number	The duration of the caller's participation in the meeting, specified in seconds.
endpoint_sid	string	The secure ID of the Conference endpoint associated with the call.
meeting_room_sid	string	The secure ID of the meeting room with which the meeting is associated.
meeting_sid	string	The secure ID of the meeting in which the calling party participated.
node	string	The IP address of the bridge node.
number_dst	string	The called party phone number.
number_src	string	The calling party phone number.
partner_sid	string	The secure ID of the partner with which the Conference endpoint is associated.
role	string	The role of the calling party in the meeting.
user_agent	string	The details about the user agent used by the calling party, if available.

A sample app_conference_call callback response:

{
    "address_dst": "\\"15162065515\\" \\u003csip:15162065515@11.22.33.44\\u003e",
    "address_src": "\\"1234\\" \\u003csip:+17605692222@12.34.56.78",
    "bridge": "conference-bridge",
    "call_sid": "69057c3e-bb90-4ed3-9c53-000000001090",
    "custom_call_type": "foreign",
    "custom_name": "\\u00271234\\u0027",
    "date_disconnected": "2021-12-14T07:08:01.000Z",
    "date_insert": "2021-12-14T07:40:27.706Z",
    "date_join": "2021-12-14T07:07:31.000Z",
    "date_start": "2021-12-14T07:07:09.000Z",
    "date_stop": "2021-12-14T07:08:01.000Z",
    "direction": "inbound",
    "disconnect_cause": 16,
    "disconnect_originator": "src",
    "disconnect_reason": "Normal",
    "duration": 50,
    "duration_meeting": 30,
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
    "node": "11.22.33.44",
    "number_dst": "15162065515",
    "number_src": "+17605692222",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "role": "participant",
    "user_agent": "CX-IVS-SBC"
}

app_conference_meeting Callback

The app_conference_meeting callback is triggered when the calling party joins a Conference meeting.

Attribute	Data Type	Description
attendee_count	integer	The total number of the meeting attendees.
audio_attendee_count	integer	The number of the attendees which used audio conferencing during the meeting.
control_attendee_count	integer	The number of the attendees which used conference controls during the meeting.
data_attendee_count	integer	The number of the attendees which sent some data during the meeting.
date_insert	string	The date and time when the detail record about the meeting was inserted into the database.
date_start	string	The date and time when the meeting started.
date_stop	string	The date and time when the meeting ended.
duration	number	The total conference duration, measured in seconds.
duration_audio	number	The duration of the meeting audio conferencing, measured in seconds.
duration_control	number	The duration of the conference control usage during the meeting, measured in seconds.
duration_data	number	The duration of the meeting during which some data was sent or received (e.g., the participants used the screensharing feature), measured in seconds.
duration_meeting	number	The duration of the meeting, measured in seconds.
duration_recording	number	The duration of the meeting during which the recording was made, measured in seconds.
duration_video	number	The duration of the meeting during which the video conferencing was used, measured in seconds.
endpoint_sid	string	The secure ID of the Conference endpoint associated with the meeting.
has_recording	boolean	Whether or not the meeting was recorded.
meeting_room_sid	string	The secure ID of the meeting room associated with the meeting.
meeting_sid	string	The secure ID of the meeting which the system uses to identify it among other meetings.
partner_sid	string	The secure ID of the partner with which the Conference endpoint is associated.
unique_attendee_count	integer	The number of the unique attendees which took part in the meeting.
video_attendee_count	integer	The number of the attendees which used video conferencing during the meeting.

The app_conference_meeting callback response:

{
    "attendee_count": 2,
    "audio_attendee_count": 2,
    "control_attendee_count": 0,
    "data_attendee_count": 0,
    "date_insert": "2021-12-14T07:40:33.843Z",
    "date_start": "2021-12-14T07:04:41.000Z",
    "date_stop": "2021-12-14T07:08:06.000Z",
    "duration": 205,
    "duration_audio": 205,
    "duration_control": 0,
    "duration_data": 0,
    "duration_meeting": 205,
    "duration_recording": 0,
    "duration_video": 0,
    "endpoint_sid": "e3ddc435-7b07-4f3a-98d5-4fe9be107652",
    "has_recording": false,
    "meeting_room_sid": "f752b4a5-b821-4322-a26f-db5cfbf014ab",
    "meeting_sid": "69057c3e-bb90-4ed3-9c53-000000000373",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "unique_attendee_count": 2,
    "video_attendee_count": 0
}

tip

Refer to our Set up Conference Callbacks Using CarrierX Portal quick start guide for more information about the Conference endpoint callbacks and how you can set them using CarrierX portal.

phonenumber_messaging_update Callback

The phonenumber_messaging_update callback is triggered when SMS/MMS messaging is enabled or disabled for a DID.

Attribute	Data Type	Description
did_sid	string	The secure ID of the rented DID.
phonenumber	string	The phone number for the rented DID in the E.164 format.
messaging	string	SMS/MMS messaging status for the rented DID. Consists of two parts: the last `enabled` request, which was sent to enable or disable this DID. Possible values are `true` to enable and `false` to disable messaging for this DID. the messaging `status`. Possible values are `enabled`, `disabled`, `failed`.

A sample phonenumber_messaging_update callback response:

{
    "did_sid":"d17a5391-1831-4d6b-adf0-5ba9a47ea6ad",
    "phonenumber":"13075220123",
    "messaging":{"enabled":true,"status":"enabled"}
}

phonenumber_order Callback

The phonenumber_order callback is triggered when a DID from an external provider has been rented successfully.

Attribute	Data Type	Description
active_capabilities	integer	The rented DID active capabilities.
callback_url	string	The URL that receives callback messages in JSON format with data about a rented DID from an external provider.
capabilities	integer	The rented DID supported capabilities.
classification_sid	string	The rented DID classification secure ID.
country_code	string	The ISO 3166-1 alpha-3 code of the rented DID country.
did_group_sid	string	The secure ID of the rented DID group.
did_sid	string	The secure ID of the rented DID.
in_country_format	string	The rented DID in a national format.
international_format	string	The rented DID in an international format.
locality	string	The locality or city of the rented DID.
lrn_sid	string	The secure ID of the Location Routing Number assigned to this rented DID.
name	string	The DID name.
partner_sid	string	The secure ID of the partner associated with the rented DID.
phonenumber	string	The phone number for the rented DID in the E.164 format.
price	number	The price of the rented DID.
state	string	The state or province of the rented DID.
status	string	The current DID status. If the DID has been rented successfully, the status returned in this field should always be `assigned`. Otherwise, no callback will be sent.
string_key_1	string	A user-defined string key.
string_key_2	string	A user-defined string key.
trunk_group_sid	string	The secure ID of the trunk group associated with the rented DID.

A sample phonenumber_order callback response:

{
    "active_capabilities":4,
    "callback_url":"https://example.com/sms-callback-url",
    "campaign_sid": null, 
    "capabilities":7,
    "classification_sid":"d1a732b9-8530-499c-926a-e85282fc7387",
    "country_code":"CAN",
    "did_group_sid":null,
    "did_sid":"d713ea8a-c2ab-492f-85ac-83279ce4543e",
    "in_country_format":"(236) 804-0634",
    "international_format":"+1 236-804-0634",
    "locality":null,
    "lrn_sid":null,
    "name":"N/A",
    "partner_sid":"0a2015db-04dc-6fd1-8bd8-ebc2a815b58b",
    "phonenumber":"12368040634",
    "price":null,
    "state":null,
    "status":"assigned"
    "string_key_1":null,
    "string_key_2":null,
    "trunk_group_sid":null
}

Call Routing

CarrierX call routing connects IP communications infrastructure with the PSTN. Call routing works slightly differently depending on the direction of the communication, either inbound or outbound.

Hosted Endpoints: Conference, FlexML, and Mediator

Inbound communications come in from the PSTN and hit the CarrierX switches, which have configured trunks. Trunks are organized and managed in trunk groups. These entities hold settings that determine how the communication is processed. Outbound communications start from an IP-based application and move through a configurable SIP trunk, and are sent to the PSTN.

Call Routing

Third-Party Endpoints

Similar to hosted endpoints, inbound communications from the PSTN reach the CarrierX switches. The communications go through a configured trunk and then your external application. Outbound communications still come from your rented DIDs, but they go through your third-party configured endpoint, which integrates with an external IP. This communication still moves to the trunk and out to the PSTN.

Third-Party Routing

The main difference is that the hosted endpoints (Conference, FlexML, and Mediator) are hosted by CarrierX. The third-party endpoint is hosted externally, not by CarrierX.

Transformations

tip

Refer to our How It Works: Transformations section to learn more about what transformations are, what transformations are available in CarrierX API, what they are used for, and how you can work with them.

Transformations are applied to endpoints, partners, DIDs, prefixes, trunk groups, and trunks. They modify values when an object is updated. Transformations have three parts: action, direction, and operands.

action is what type of modification will be made. For example, rewrite_to rewrites the destination phone number.
direction determines to which direction of traffic the transformation will apply. For example, if we set direction to outbound, the specific transformation will apply to sending voice calls only.
operands are the items that are being acted upon. For example, rewrite_to accepts two operands: the value to replace and the value that it is going to be replaced with.

note

By default, only X- headers can be added and updated.
Note, that some of the transormation fields support expandable macro variables.

Attribute	Data Type	Description
action	string	The action to be executed for the transformation. Refer to the sections below for a list of all actions.
direction	string	The direction of communication that the transformation applies to. Values accepted in this field are: `any`---the selected transformation is applied when the entity is sending or receiving calls. `inbound`---the selected transformation is applied when the entity is receiving calls. `outbound`---the selected transformation is applied when the entity is sending calls. `undirected`---the selected transformation is applied unrelated to the direction.
operands	array	The values to be transformed. Operands can include set values or regular expressions.

Transformations look like the following:

{
    "action":"set_header_parameter",
    "direction":"any",
    "operands":["P-Charging-Vector","orig-ioi","privateSIP"]
}

Note that you can use regular expressions in transformations. For example, the following will check if the phone number has a 1 prefix and add one if not.

{
    "transformations": [
        {
            "action": "rewrite_to",
            "direction": "any",
            "operands": ["^([2-9]\\d{9})$", "1\\1"]
        },
        {
            "action": "rewrite_from",
            "direction": "any",
            "operands": ["^([2-9]\\d{9})$", "1\\1"]
        }
    ]
}

if_match

The if_match action is used to add conditions based on which other transformations are applied.

The action accepts from three to 100 operands: if_match(value, match, action, arg1, argX)

Operand	Data Type	Description
value	string	The string value with interpolated fields.
match	string	The regular expression to match.
action	string	The action to take if the regular expression succeeds. This action is another transformation.
arg1	string	The first argument of the transformation action.
argX	string	The next arguments of the transformation action.

info

The fourth (arg1) and up operands will be the arguments for another transformation. E.g., if the transformation selected is reject, then the only argument for it will be the reject reason, thus the total number of operands will be equal to four; if the transformation selected is lookup_rn, then you will need to add nine arguments for it, thus the total number of operands will be twelve.

A sample if_match transformation:

{
    "action": "if_match",
    "direction": "inbound",
    "operands": [
        "{{stir_verstat}}",
        "TN-Validation-Failed",
        "reject",
        "forbidden"
    ]
}

lookup_cic

The lookup_cic action is used to lookup the CIC (Carrier Identification Code) information for calls to toll-free phone numbers.

The action accepts eight operands: lookup_cic(force, lata, phonenumber_src, phonenumber_dst, destination, on_failure, input_format_src, input_format_dst)

Operand	Data Type	Description
force	string	Force lookup mode. Values accepted in this field are: `false` to lookup only if the CIC information is empty. `true` to always lookup the CIC, even if the `cic` field in the `To` header is already set. The default value is `false`.
lata	string	LATA: Local Access and Transport Area, a geographic code representing the location of the call origination. Note, that this operand is required but it does not have a default value, therefore it must always be specified.
phonenumber_src	string	The call origination phone number. The default value is `{{src}}`.
phonenumber_dst	string	The destination toll-free phone number we are looking up the CIC for. The default value is `{{dst}}`.
destination	string	The destination field where the CIC will be stored. The default value is `cic`. If this value is `cic` (default), the CIC will be stored in the `cic` field of the `To` header. If set to some other custom value, the CIC will be stored in a custom header with a different name.
on_failure	string	The behavior on the transformation request failure. Values accepted in this field are: `die` to reject the call with the `503` status code. `ignore` to continue with the call passing the original `cic` value if it is present, but the system performed the lookup due to `force` operand set to `true`. If the `cic` value is missing, continue with the call but do not add `cic` attributes to it. `original_cic_or_die` to pass the original `cic` value if it is present, but the system performed the lookup due to `force` operand set to `true`. Or reject the call with the `503` status code if the value is missing. The default value is `ignore`.
input_format_src	string	The source number (`phonenumber_src`) input format. The transformation will try to determine if the number is domestic or international, and only perform a lookup if it looks like domestic. Values accepted in this field are: `e164` for the number to be considered domestic and perform a lookup if the number is 11 digits long and starts with `1`. Otherwise, the phone number is considered international, and no lookup is performed. `guess` for the number to be considered domestic and perform a lookup if the number starts with `+1` and is 11 digits long. If the number does not start with `+`, but starts with `1` and is 11 digits long, then it is considered domestic, and a lookup is performed. If the number does not start with `+` and is 10 digits long, then the number type is set to `guess` and a lookup is performed. Otherwise, the phone number is considered international and no lookup is performed. `ignore_plus` is used if the source may add extraneous `+` that should not be trusted. If the number is 11 digits long, and starts with `1`, then the number is considered domestic and a lookup is performed. If the number is 10 digits long, then the number type is set to `guess` and a lookup is performed. Otherwise, the phone number is considered international and no lookup is performed. The default value is `guess`.
input_format_dst	string	The destination number (`phonenumber_dst`) input format. Values in this field are similar to those of the `input_format_src` above.

note

Only the force operand is required. All the other operands are optional.

A sample lookup_cic transformation:

{
    "action": "lookup_cic",
    "direction": "inbound",
    "operands": [
        "false",
        "490",
        "{{src}}",
        "{{dst}}",
        "cic",
        "ignore",
        "e164",
        "guess"
    ]
}

lookup_cnam

The lookup_cnam action is used to lookup the CNAM information for the phone number.

The action accepts four operands: lookup_cnam(force, default, number, target)

Operand	Data Type	Description
force	string	Force lookup mode. Values accepted in this field are: `false` to only lookup if the CNAM information is empty. `numeric` that is similar to `false`, but also performs the lookup if the value matches the `/^\+*\d+$/` regular expression (i.e., it looks like a phone number or an extension). `true` to always lookup CNAM, even if the CNAM information is already filled. The default value is `true`.
default	string	The default string to use if no CNAM information can be found. Values accepted in this field are: `''`, `{{src}}`, etc. The default value is `''`.
number	string	The number to lookup. The default value is `{{src}}`.
target	string	The target where the result will be saved. If this value is set `to` or `from`, it should be written to the name portion of the appropriate field. Otherwise, if it is set to a custom header name, it may be equal to the entire value of a custom header. The default value is `from`.

A sample lookup_cnam transformation:

{
    "action": "lookup_cnam",
    "direction": "inbound",
    "operands": [
        "true",
        "{{src}}",
        "{{src}}",
        "from"
    ]
}

lookup_rn

The lookup_rn action is used to lookup the routing number and return it so that it could be used instead of the source or destination number.

The action accepts nine operands: lookup_rn(force, always, phonenumber, destination, on_failure, input_format, output_format_domestic, output_format_international, output_format_guess_not_found)

Operand	Data Type	Description
force	boolean	Force lookup mode. If `true`, always lookup the routing number, even if the `npdi` field is already set in the SIP URI. If `false`, the number from the `rn` attribute will be used instead. The default value is `false`.
always	boolean	Always include the routing number. If `true`, always add the routing number to the destination field. If `false`, this will only be included if a routing number was found. The default value is `false`.
phonenumber	string	The phone number to look up. Usually `{{dst}}` (destination) to look up the routing number for the called party or `{{src}}` (source) for the calling party. The default value is `{{dst}}`.
destination	string	The destination field where the routing number will be stored. If `to` or `from`, the routing number will be stored using the `npdi` and `rn` attributes. If set to some other value, the routing number will be stored in a custom header of this name. The default value is `to`.
on_failure	string	The behavior on the transformation request failure. Values accepted in this field are: `die` to reject the call with the `503` status code. `ignore` to continue with the call passing the original `npdi` value if it is present, but the system performed the lookup due to `force` operand set to `true`. If the `npdi` value is missing, continue with the call but do not add `npdi=true` or `rn` headers to it. `original_npdi_or_die` to pass the original `npdi` value if it is present, but the system performed the lookup due to `force` operand set to `true`. Or reject the call with the `503` status code if the value is missing. The default value is `die`.
input_format	string	The destination number input format. The transformation will try to determine if number is domestic or international, and only perform lookup if it looks like domestic. Values accepted in this field are: `e164` for the number to be considered domestic and perform lookup if the number is 11 digits long and starts with `1`. Otherwise, the phone number is considered international and lookup is not performed. `guess` for the number to be considered domestic and perform lookup if the number starts with `+1` and is 11 digits long. If the number does not start with `+`, but starts with `1` and is 11 digits long, then it is considered domestic and lookup is performed. If the number does not start with `+` and is 10 digits long, then the number type is set to `guess` and lookup is performed. Otherwise, the phone number is considered international and lookup is not performed. `ignore_plus` is used if the source may add extraneous `+` that should not be trusted. If the number is 11 digits long, and starts with `1`, then the number is considered domestic and lookup is performed. If the number is 10 digits long, then the number type is set to `guess` and lookup is performed. Otherwise, the phone number is considered international and lookup is not performed. The default value is `guess`.
output_format_domestic	string	The output format for the numbers considered domestic or with the type set to `guess` by the `input_format` operand and LRN found. Values accepted in this field are: `domestic` to output the number in a 10-digit format. `e164` to output the number in the E.164 11-digit format. `e164_with_plus` to output the number in the E.164 11-digit format with `+`. The default value is `domestic`.
output_format_international	string	The output format for the numbers considered international by the `input_format`. Values accepted in this field are: `e164` to output the number in the E.164 11-digit format without `+`. `e164_with_plus` to output the number in the E.164 11-digit format with `+`. `passthrough` to use the original number exactly as it was passed. The default value is `passthrough`.
output_format_guess_not_found	string	The output format if the destination number type is set to `guess` by the `input_format` operand and no lookup routing number was found. Values accepted in this field are: `domestic` to output the number in a 10-digit format. `e164` to output the number in the E.164 11-digit format without `+`. `e164_with_plus` to output the number in the E.164 11-digit format with `+`. `passthrough` to use the original number exactly as it was passed. The default value is `passthrough`, non-default values will be applied only if the `always` operand is set to `true`.

A sample lookup_rn transformation:

{
    "action": "lookup_rn",
    "direction": "inbound",
    "operands": [
        "true",
        "true",
        "{{src}}",
        "from",
        "ignore",
        "e164",
        "domestic",
        "e164_with_plus",
        "passthrough"
    ]
}

reject

The reject action is used to reject the call with one of the supported reasons.

The action accepts from one to two operands: reject(reason, message)

Operand	Data Type	Description
reason	string	The reject reason. Refer to the table below for a complete list of the reasons available.
message	string	The additional message about the reject reason. This is an optional field.

note

Only the reason operand is required. The message operand can be omitted. No message will be returned to the caller in this case.

A sample reject transformation:

{
    "action": "reject",
    "direction": "inbound",
    "operands": [
        "busy"
    ]
}

Reject Reasons

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

An example of the reject transformation with intermediary-rejected as a reject reason. My reason for rejecting the call will be returned as the additional message to the caller as a part of the Call-Info SIP header:

{
    "action": "reject",
    "direction": "inbound",
    "operands": [
        "intermediary-rejected",
        "My reason for rejecting the call"
    ]
}

A sample Call-Info SIP header returned from the above reject transformation with the intermediary-rejected reject reason:

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

rewrite_from

The rewrite_from action is used to rewrite the phone number of the incoming call.

The action accepts two operands: rewrite_from(pattern, replace)

Operand	Data Type	Description
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.

A sample rewrite_from transformation

{
    "action": "rewrite_from",
    "direction": "any",
    "operands": [
        "^([2-9]\\d{9})$",
        "1\\1"
    ]
}

rewrite_from_header_param

The rewrite_from_header_param action is used to replace the parameters of the From header.

The action accepts three operands: rewrite_from_header_param(parameter, pattern, replace)

Operand	Data Type	Description
parameter	string	The parameter of the `From` header to change. The parameters, which can be safely changed without dropping the call, are: `caller-rn`, `cnam`, and `isup-oli`.
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.

A sample rewrite_from_header_param transformation

{
    "action": "rewrite_from_header_param",
    "direction": "any",
    "operands": [
        "cnam",
        "(.{1,14})",
        "\\1*"
    ]
}

rewrite_header

The rewrite_header action is used to replace the header (or a part of it) you specify as an operand with the new values, or create it, in the case the call data lacks it.

The action accepts four operands: rewrite_header(header, pattern, replace, default)

Operand	Data Type	Description
header	string	The header to change.
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.
default	string	If the header is missing from the call, it will be created and set to the `default` value.

A sample rewrite_header transformation:

{
    "action": "rewrite_header",
    "direction": "any",
    "operands": [
        "X-Custom-Header",
        ":5060",
        ":6060",
        "sip:10.1.5.200:5060"
    ]
}

rewrite_header_parameter

The rewrite_header_parameter action is used to replace the parameter of the header you specify as an operand with the new value, or create it, in the case the call data lacks it.

The action accepts five operands: rewrite_header_parameter(header, parameter, pattern, replace, default)

Operand	Data Type	Description
header	string	The header in which the `parameter` will be changed.
parameter	string	The header parameter to change.
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.
default	string	If the parameter is missing from the call, it will be created and set to the `default` value.

A sample rewrite_header_parameter transformation:

{
    "action": "rewrite_header_parameter",
    "direction": "any",
    "operands": [
        "Remote-Party-ID",
        "privacy",
        "full",
        "cnam",
        "id"
    ]
}

rewrite_to

The rewrite_to action is used to rewrite the destination phone number.

The action accepts two operands: rewrite_to(pattern, replace)

Operand	Data Type	Description
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.

A sample rewrite_to transformation:

{
    "action": "rewrite_to",
    "direction": "any",
    "operands": [
        "^([2-9]\\d{9})$",
        "1\\1"
    ]
}

rewrite_to_header_param

The rewrite_to_header_param action is used to replace the parameters of the To header.

The action accepts three operands: rewrite_to_header_param(parameter, pattern, replace)

Operand	Data Type	Description
parameter	string	The parameter of the `To` header to change.
pattern	string	The value to be replaced. Also accepts regular expressions.
replace	string	The new value with which the `pattern` will be replaced.

A sample rewrite_to_header_param transformation:

{
    "action": "rewrite_to_header_param",
    "direction": "any",
    "operands": [
        "npdi",
        "yes",
        "no"
    ]
}

set_header

The set_header action is used to add a new header.

note

If the value is set to an empty string and there is a pre-existing header, it will be cleared.

The action accepts two operands: set_header(header, value)

Operand	Data Type	Description
header	string	The header to be added.
value	string	The value for the header.

note

Any headers added would still need to be in the legB SIP_RELAY_HEADERS to be sent to the destination endpoint.

A sample set_header transformation:

{
    "action": "set_header",
    "direction": "any",
    "operands": [
        "X-Custom-Header",
        "sip:10.1.5.200:5060"
    ]
}

set_header_parameter

The set_header_parameter action is used to set a parameter to an existing header.

The action accepts three operands: set_header_parameter(header, parameter, value)

Operand	Data Type	Description
header	string	The header which is going to be modified.
parameter	string	The header parameter to be set.
value	string	The value for the header parameter. If the value is `""` and the header parameter exists, it will be deleted.

A sample set_header_parameter transformation

{
    "action": "set_header_parameter",
    "direction": "any",
    "operands": [
        "P-Charging-Vector",
        "orig-ioi",
        "privateSIP"
    ]
}

set_user_data

The set_user_data action is used to add custom user data to the call detail records. The transformation saves the data as a JSON object to the user_data attribute of the Call Detail Record object.

The action accepts two operands: set_user_data(key, value)

Operand	Data Type	Description
key	string	A user-defined custom key that will be displayed as a part of the `user_data` attribute of the call detail record.
value	string	A user-defined custom value of the key that will be displayed as a part of the `user_data` attribute of the call detail record.

A sample set_user_data transformation

{
    "action": "set_user_data",
    "direction": "any",
    "operands": [
        "identity",
        "{{SipHeader_Identity}}"
    ]
}

sms_normalize

By default, all phone numbers for the SMS Object are always treated as E.164 international numbers.

The sms_normalize action is used to add a corresponding country prefix to the SMS Object from and/or to fields. This transformation is based on the Phonenumber Lookup object mechanism and the Phonenumber Lookup logic. With this transformation, for example, for all outbound messages you can indicate the country you need and by default all SMS messages with domestic number format in the to field will be routed to phone numbers inside that country, i.e. the system will be automatically converting such numbers to the E.164 format.

The action accepts five operands: sms_normalize(guess, country_code, field, on_failure, output_format)

Operand	Data Type	Description
guess	string	Tells the system to make a guess that the DID this transformation is applied to is either an E.164 or a domestic (in-country) number. This operand is activated if the `country_code` lookup step (see below) results in finding out that the corresponding DID matches both, an E.164 and a domestic phone number. Values accepted in this field are: `e164` in which case the system will try to make a guess that this DID is an international phone number and proceed further `in_country` in which case the system will try to make a guess that the DID is a domestic number. In case of USA such number will be a part of NANP, the North American Numbering Plan. The default value is `e164`. If the `guess` step does not bring any result, the system proceeds to the `on_failure` step.
country_code	string	The ISO 3166-1 alpha-3 code of the country. To check, whether this number is a domestic (in-country) number, the system uses the`country_code` query parameter, to see if the number passed could be valid in the country specified in the request. This operand the system that before routing any outbound SMS or accepting any inbound SMS without the `+` prefix, it should first check such phone number and verify whether it is a valid number in that country. If a valid number is found, the system adds the corresponding country code prefix to the phone number and the SMS is processed further (e.g. for the United Kingdom, the `+44` prefix will be added), no further checks are made. If no valid number is found, the system tries to find a match for this number among domestic (in-country) and E.164 numbers. Here, tree options are possible: if a match is found and the number is only a valid domestic number or only a valid E.164 number, the SMS is processed further, no further checks are made. if no match is found, the system switches to the `on_failure` step. if the number matches both, domestic and E.164, the system switches to the `guess` step. If the`country_code` query parameter is not set, the system uses `country_code`=`USA` by default.
field	string	The SMS Object field this transformation must be applied to. Valued accepted in this field are: `from` `to` (default)
on_failure	string	The behavior on the transformation request failure. Only one value is accepted in this field: `ignore` to continue with the SMS sending/receiving.
output_format	string	The output format of the destination phone number. Only one value is accepted in this field: `e164` (default)

A sample sms_normalize transformation

{
    "action": "sms_normalize",
    "direction": "outbound",
    "operands": [
        "e164",
        "USA",
        "to",
        "ignore",
        "e164"
    ]
}

stir_validate

tip

Refer to our How It Works: STIR/SHAKEN section to learn more about what STIR/SHAKEN is, what it is used for, and how CarrierX allows you to use STIR/SHAKEN in your workflow.

The stir_validate action is used to validate the call and returns data that can be used with other transformations.

The action does not accept any operands, but instead enables the use of the following variables:

{{stir_attest}} for the attestation level used for the call.
{{stir_origid}} for the ID of the call originator.
{{stir_verstat}} for the TN validation result (available values include TN-Validation-Passed, TN-Validation-Failed, and No-TN-Validation).

A sample stir_validate transformation

{
    "action": "stir_validate",
    "direction": "any",
    "operands": []
}

Core Concepts

Batch Operations​

Callbacks​

sms and callback_url Callback​

app_mediator Callback​

app_conference_call Callback​

app_conference_meeting Callback​

phonenumber_messaging_update Callback​

phonenumber_order Callback​

Call Routing​

Transformations​

if_match​

lookup_cic​

lookup_cnam​

lookup_rn​

reject​

Reject Reasons​

rewrite_from​

rewrite_from_header_param​

rewrite_header​

rewrite_header_parameter​

rewrite_to​

rewrite_to_header_param​

set_header​

set_header_parameter​

set_user_data​

sms_normalize​

stir_validate​

Batch Operations

Callbacks

sms and callback_url Callback

app_mediator Callback

app_conference_call Callback

app_conference_meeting Callback

phonenumber_messaging_update Callback

phonenumber_order Callback

Call Routing

Transformations

if_match

lookup_cic

lookup_cnam

lookup_rn

reject

Reject Reasons

rewrite_from

rewrite_from_header_param

rewrite_header

rewrite_header_parameter

rewrite_to

rewrite_to_header_param

set_header

set_header_parameter

set_user_data

sms_normalize

stir_validate