Create SMS

This request creates an SMS control. Depending on its status, the SMS control is saved as a concept or scheduled for sending straight away.

The server has to support SMS messages in order for this request to succeed. See the system capabilities resource for more information.

Resource

POST /sms

Parameters

None

Payload

An SMS Control object containing the message contents and the recipients.

The SMS control must include a sender in fromAddressee and at least one recipient in toAddressees. The sender is an Addressee with the role rtFrom, the phone number the SMS is sent from as address, and the addressable it belongs to.

Each recipient is defined by a Referable, which can be either an X1List or an Addressable:

Addressable	The phone number to send to is set in `phoneNumber`.
X1List	The individual recipients of the list are set in `listAddresses`, each as an SMS List Address with a phone number and the addressable it belongs to.

The status determines what happens after creation:

`concept`	The SMS control is saved as a draft and can be edited later. Nothing is sent.
`scheduled`	The SMS control is scheduled for sending straight away, or on the `sendOnDate` if one is set.

The smsObjectType determines how the SMS control is used:

`control`	A regular SMS that can be sent.
`template`	A template that can be used as the basis for other SMS controls. Templates are not sent.

When an SMS control is sent, an SMS message is created for each individual recipient and linked to the SMS control. This makes it possible to retrieve the status of each individual message.

Note: the SMS messages created by an SMS control always get the status scheduled. As a result, they don’t appear in the communication overview immediately but are added automatically after a minute or two.

Note: not all SMS providers support including a reply address. If no reply address is set in smsHttpReplyTo then the default caller-id is used.

Response

An SMS Control object containing the created SMS control with the object IDs the system has generated.

Context

Authorization

User

Errors

Common Errors

Example

Request

POST https://xelion.nl/api/v1/master/sms

Payload

{
    "fromAddressee": {
        "role": "rtFrom",
        "address": "+31612345678",
        "addressable": {
            "oid": "1556377",
            "objectType": "Person"
        },
        "addresseeLabel": "John Smith",
        "objectType": "Addressee"
    },
    "subject": "Bird lives",
    "messageText": "Bird lives!",
    "wantConfirmation": false,
    "status": "scheduled",
    "sendOnDate": "2026-01-01 10:00:00",
    "smsObjectType": "control",
    "toAddressees": [
        {
            "referable": {
                "oid": "1557797",
                "objectType": "Person"
            },
            "phoneNumber": "+31612345679",
            "objectType": "RelSMSControlReferable"
        },
        {
            "referable": {
                "oid": "1602214",
                "objectType": "X1List"
            },
            "listAddresses": [
                {
                    "phoneNumber": "+31612345670",
                    "addressable": {
                        "oid": "1558012",
                        "objectType": "Person"
                    },
                    "objectType": "SMSListAddress"
                },
                {
                    "phoneNumber": "+31612345671",
                    "addressable": {
                        "oid": "1558047",
                        "objectType": "Person"
                    },
                    "objectType": "SMSListAddress"
                }
            ],
            "objectType": "RelSMSControlReferable"
        }
    ],
    "substitutionVars": [
        {
            "valueName": "introduction",
            "valueDescription": "This is the introduction",
            "value": "G'day mate",
            "oid": "2545479",
            "objectType": "SMSVariable"
        }
    ],
    "smsHttpReplyTo": "John Smith",
    "objectType": "SMSControl"
}

Response

{
    "object": {
        "fromAddressee": {
            "commonName": "John Smith",
            "role": "rtFrom",
            "address": "+31612345678",
            "addressable": {
                "commonName": "John Smith",
                "oid": "1556377",
                "objectType": "Person"
            },
            "addresseeLabel": "John Smith",
            "oid": "2121030",
            "objectType": "Addressee"
        },
        "sendOnDate": "2026-01-01 10:00:00",
        "subject": "Bird lives",
        "wantConfirmation": false,
        "toAddressees": [
            {
                "referable": {
                    "commonName": "Charlie Parker",
                    "oid": "1557797",
                    "objectType": "Person"
                },
                "phoneNumber": "+31612345679",
                "oid": "2121031",
                "objectType": "RelSMSControlReferable"
            },
            {
                "referable": {
                    "commonName": "Customers",
                    "oid": "1602214",
                    "objectType": "X1List"
                },
                "phoneNumber": "",
                "listAddresses": [
                    {
                        "phoneNumber": "+31612345670",
                        "addressable": {
                            "commonName": "Dizzy Gillespie",
                            "oid": "1558012",
                            "objectType": "Person"
                        },
                        "oid": "2121033",
                        "objectType": "SMSListAddress"
                    },
                    {
                        "phoneNumber": "+31612345671",
                        "addressable": {
                            "commonName": "Thelonious Monk",
                            "oid": "1558047",
                            "objectType": "Person"
                        },
                        "oid": "2121034",
                        "objectType": "SMSListAddress"
                    }
                ],
                "oid": "2121032",
                "objectType": "RelSMSControlReferable"
            }
        ],
        "substitutionVars": [],
        "messageText": "Bird lives!",
        "status": "scheduled",
        "smsObjectType": "control",
        "smsHttpReplyTo": "John Smith",
        "phoneLine": {
            "permissions": "ReadWriteRemove",
            "commonName": "John Smith",
            "oid": "1651226",
            "objectType": "XCCPhoneLine"
        },
        "permissions": "ReadWriteRemove",
        "commonName": "Bird lives",
        "oid": "2121029",
        "objectType": "SMSControl"
    },
    "links": [
        {
            "rel": "self",
            "href": "https://xelion.nl/api/v1/master/sms/2121029",
            "method": "GET"
        }
    ]
}