SMS Object

This section outlines the SMS object. SMS object is used for both SMS and MMS.

SMS Object attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
date_changed read only	string	The date and time when the message was last changed.
date_created read only	string	The date and time when the message was created.
date_status_changed read only	string	The date and time when the message status last changed.
direction read only	string	The direction of the message. Values accepted in this field are: `any` for both the received and sent messages. `inbound` for received messages. `outbound` for sent messages. `undirected` for the messages which direction could not be determined.
from create	string	The phone number that the message will be from, in the E.164 format. Note, that legacy users may still see the old naming instead (`from_did`).
group_recipients create	array	The list of phone numbers that an inbound or outbound mms group message is delivered to, in E.164 format. Please note, that group chat messaging is available for `mms` type of messaging only. If `group_recipients` are specified, the message `type` can only be `mms`. Please also note, that in case of group chat messaging with multiple recipients the sender is charged for each outbound message individually. The maximum number of DIDs you can use in this field for a group chat is 10 (including the sender's DID).
mcc read only	integer	The mobile country code.
media_urls create	array	The list of URLs for media resources, if `type` of message is set to `mms`.
message create	string	The message body.
message_segments read only	integer	The quantity of 160-symbols segments of an `sms` message. Messages with `type` set to `mms` always consist of a single segment.
message_sid read only	string	The message secure ID.
mnc read only	integer	The mobile network code.
partner_sid read only	string	The secure ID of the partner this message belongs to.
price read only	string	The price in US dollars determined for the message to be delivered.
status read only	string	The status of the message. Values accepted in this field are: `delivered` for the outgoing messages that have been successfully delivered to the recipient. `failed` for the outgoing messages that failed for some reason. `internal_error` for the outgoing messages that encountered any type of internal system errors while being sent to the recipient. `queued` for the outgoing messages accepted by the system, but not yet sent. `received` for the incoming messages that are received by the rented DID. `sending_failed` for the outgoing messages that passed through either `internal_error` or `sending_timed_out` status. `sending_timed_out` for the outgoing messages that stuck at the `queued` status for a certain system-set timeout. `sent` for the outgoing messages that were sent to the recipient. `timed_out` for the outgoing messages that have been sent, but then stuck at the `sent` status for a certain system-set timeout. `undelivered` for the outgoing messages that passed through the `sent` status, but could not be delivered to the recipient for some reason (e.g., the destination number is unreachable).
to create	string	The phone number that the message will be delivered to, in E.164 format. Note, that legacy users may still see the old naming instead (`to_did`).
type read only	string	The type of message. Values returned in this field are `mms` and `sms`. The default value is `sms` if both, the `media_urls` and `group_recipients` arrays, are empty. The value is `mms` if any or both of those arrays contain items.
user_data create update	string	Some additional user-defined data added to the message. The field max length is `2000`.

Sample SMS Object

{
    "date_changed": "2024-04-27T09:34:01.637Z",
    "date_created": "2024-01-18T21:01:13.415Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "mcc": null,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": null,
    "status": "queued",
    "to": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}

Send Message

This request sends a message from a rented DID.

post

/sms/messages

Sample

A sample POST request to send an SMS:

curl -X POST \
'https://api.carrierx.com/core/v2/sms/messages' \
-H 'Content-Type: application/json' \
--data-binary '{"from":"15162065575", "to":"15162065574", "message":"This is a test message"}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the SMS object:

{
    "date_changed": "2023-12-06T15:18:30.084Z",
    "date_created": "2023-12-06T15:18:29.189Z",
    "date_status_changed": null,
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "mcc": null,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": null,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": null,
    "status": "queued",
    "to": "15162065574",
    "type": "sms",
    "user_data": "test_message"
}

note

Please note, that

to send messages from a rented DID you need to enable SMS/MMS messaging on that DID first.
an MMS message can have a text body of up to 1600 characters and up to 10 media items such as images with the total size limited to 3 MB. If you exceed these restrictions, the message will fail and will not be sent out.

Required Scopes

To create an SMS object, the partner must have one of the following scopes enabled:

sms.manage
sms.create

Body Arguments

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

Required fields to send an SMS message are:

from (some legacy users may still see from_did, i.e. the old naming)
message
to (some legacy users may still see to_did, i.e. the old naming)

Required fields to send an MMS message are:

group_recipients: if this field contains at least one phone number and the message direction is outbound, the message type must be set to mms. If the media_urls attribute is already specified, group_recipients is optional for the mms message
from (some legacy users may still see from_did, i.e. the old naming)
media_urls: if the group_recipients attribute is already specified, media_urls is optional for the mms message
message: is required if the media_urls field is empty
to (some legacy users may still see to_did, i.e. the old naming)

note

Please note, that sending SMS from short code and MMS to phone numbers outside the US is disabled.

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

Get Messages

This request returns a list of received and sent messages.

get

/sms/messages

Sample

A sample GET request to get messages matching the criteria in the request URL:

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

Response

200 status code with a list of SMS objects:

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_changed": "2024-04-06T15:18:30.084Z",    
            "date_created": "2024-04-06T15:18:29.189Z",
            "date_status_changed": "2024-04-06T15:18:30.046Z",
            "direction": "outbound",
            "from": "15162065575",
            "group_recipients": [],
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message",
            "message_segments": 1,
            "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
            "mnc": 999,
            "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
            "price": "0.01",
            "status": "delivered",
            "to": "15162065574",
            "type": "sms",
            "user_data": "test_message"
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "next": "https://qa-api.carrierx.com/core/v2/sms/messages?limit=1&filter=direction+eq+outbound+and+type+eq+sms&offset=1"
    },
    "total": null
}

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

Required Scopes

To get information about SMS objects, the partner must have one of the following scopes enabled:

sms.manage
sms.read

Get Message by SID

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

get

/sms/messages/{message_sid}

Sample

A sample GET request to get a message, targeted by secure ID:

curl -X GET \
'https://api.carrierx.com/core/v2/sms/messages/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the SMS object:

{
  "date_changed": "2024-04-06T15:18:30.084Z",    
  "date_created": "2024-04-06T15:18:29.189Z",
  "date_status_changed": "2024-04-06T15:18:30.046Z",
  "direction": "outbound",
  "from": "15162065575",
  "group_recipients": [],
  "mcc": 310,
  "media_urls": [],
  "message": "This is a test message",
  "message_segments": 1,
  "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
  "mnc": 999,
  "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
  "price": "0.01",
  "status": "delivered",
  "to": "15162065574",
  "type": "sms",
  "user_data": "test_message"
}

This request is enabled for Field Filtering.

Required Scopes

To get information about an SMS object, the partner must have one of the following scopes enabled:

sms.manage
sms.read

Path Arguments

Parameter	Data Type	Description
message_sid required	string	The message secure ID.

Update Message

This request updates a message, targeted by secure ID.

patch	/sms/messages/{message_sid}
put	/sms/messages/{message_sid}

Sample

A sample PATCH request to update the SMS object, targeted by secure ID, with the values in the request body:

curl -X PATCH \
'https://api.carrierx.com/core/v2/sms/097b49df-c54e-4eaf-97d0-89cf7d5a655b' \
-H 'Content-Type: application/json' \
--data-binary '{"user_data":"updated_test_message"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response

200 status code with a serialized copy of the updated SMS object:

{
    "date_changed": "2024-01-06T15:18:30.084Z",    
    "date_created": "2023-12-06T15:18:29.189Z",
    "date_status_changed": "2023-12-06T15:18:30.046Z",
    "direction": "outbound",
    "from": "15162065575",
    "group_recipients": [],
    "mcc": 310,
    "media_urls": [],
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "097b49df-c54e-4eaf-97d0-89cf7d5a655b",
    "mnc": 999,
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "price": "0.01",
    "status": "delivered",
    "to": "15162065574",
    "type": "sms",
    "user_data": "updated_test_message"
}

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

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 payload will be updated, all other attributes and values will remain the same. The message secure ID is passed in the query URL, and the values to be modified are passed in the request body.
A PUT request can be used to update an entire SMS object. The message secure ID is passed in the query URL, and the entire SMS object is passed in the request body.

note

Note, while all the fields must be present in a PUT request, not all the attribute values may be modified after the initial creation, because when created, some of them become read-only.

Required Scopes

To update an SMS object, the partner must have one of the following scopes enabled:

sms.manage
sms.update

Path Arguments

Parameter	Data Type	Description
message_sid required	string	The message secure ID.

Body Arguments

JSON representation of the fields and values to be updated.

The field that can be modified is user_data.

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

SMS Object

SMS Object attributes​

Sample SMS Object​

Send Message​

Sample​

Response​

Required Scopes​

Body Arguments​

Get Messages​

Sample​

Response​

Required Scopes​

Get Message by SID​

Sample​

Response​

Required Scopes​

Path Arguments​

Update Message​

Sample​

Response​

Required Scopes​

Path Arguments​

Body Arguments​

SMS Object attributes

Sample SMS Object

Send Message

Sample

Response

Required Scopes

Body Arguments

Get Messages

Sample

Response

Required Scopes

Get Message by SID

Sample

Response

Required Scopes

Path Arguments

Update Message

Sample

Response

Required Scopes

Path Arguments

Body Arguments