Methods

Objects

SMS REST API

Alternatively to our JSON-RPC API, you can use our REST endpoints to send, retrieve or list SMS resources attached to your account.

Please remember that all API endpoints below have to be appended to https://api.callr.com/rest/v1.1

HTTP Method Endpoint API Version Description
GET /sms 1.1 Retrieve the list of SMS sent or received through your account
POST /sms 1.1 Create and send an SMS resource
GET /sms/send 1.1 Create and send an SMS resource with query string parameters
GET /sms/<hash> 1.1 Retrieve a specific SMS resource based on its hash

Endpoints

GET /sms

Description

Retrieve the list of SMS sent or received through your account

Parameters

Parameter Type Description NULL
type string Type of SMS to retrieve
Values: "IN", "OUT"
NO
from string Retrieve from date.
Format: datetime (YYYY-MM-DD HH:MM:SS in UTC timezone. Example: "2012-04-24 23:42:00")
NO
to string Retrieve to date.
Format: datetime (YYYY-MM-DD HH:MM:SS in UTC timezone. Example: "2012-04-24 23:42:00")
NO

Result

Type Description Format/Object
array SMS list Array of SMS objects.

Example request

#!/bin/bash

login='API_LOGIN'
password='API_PASSWORD'

curl -G "https://api.callr.com/rest/v1.1/sms" \
--user "$login:$password" \
--data-urlencode type="OUT" \
--data-urlencode from="2024-10-15 10:14:45" \
--data-urlencode to="2024-10-15 10:14:45" \
;

            

POST /sms

Description

Create and send an SMS resource

Parameters

Parameter Type Description NULL
from string The SMS sender. If empty, a shared shortcode will be automatically selected depending on the destination carrier. Otherwise, it must be either a dedicated shortcode, or alphanumeric (at least one character - cannot be digits only).
Max length = 11 characters.

Depending on your account configuration, you may have to ask our support team to authorize custom Sender IDs. "SMS" is always authorized.
Format: sms_sender (a-zA-Z0-9, space, dash, underscore - must contain at least one alpha character)
NO
to string The SMS recipient.
Format: phone_number (International E.164 format "+CCNSN". Example: "+16467890800", "+447890123456", or "+33678912345")
NO
body string Text message. We auto-detect the encoding needed (GSM 03.38 or UNICODE), or you can force the encoding with options.force_encoding (see the "options" parameter). You always send UTF-8 JSON strings - encoding is done at SMS interconnections level. Depending on the encoding, messages may be split into parts at 153 (GSM) or 67 (UNICODE) characters.

One SMS sent with this method may be billed as multiple SMS parts. You can check the number of parts sent with the method "sms.get".

If you are using a custom sender, you can use the special string %STOPNUM% -- it will be replaced by the STOP number.
NO
options object SMS Options. Omit parameter to use default values.
Object: SMS.Options
YES

Result

Type Description Format/Object
string SMS ID Format: hash (Unique object identifier)

Example request

#!/bin/bash

login='API_LOGIN'
password='API_PASSWORD'
json='
{
    "to": "+16469820800",
    "from": "SMS",
    "body": "An SMS sent with the CALLR REST API."
    "options": null
}'

curl -X POST "https://api.callr.com/rest/v1.1/sms" \
--user "$login:$password" \
-H "Content-Type: application/json" \
-d $json

            

GET /sms/send

Description

Create and send an SMS resource with query string parameters

Parameters

Parameter Type Description NULL
from string The SMS sender. If empty, a shared shortcode will be automatically selected depending on the destination carrier. Otherwise, it must be either a dedicated shortcode, or alphanumeric (at least one character - cannot be digits only).
Max length = 11 characters.

Depending on your account configuration, you may have to ask our support team to authorize custom Sender IDs. "SMS" is always authorized.
Format: sms_sender (a-zA-Z0-9, space, dash, underscore - must contain at least one alpha character)
NO
to string The SMS recipient.
Format: phone_number (International E.164 format "+CCNSN". Example: "+16467890800", "+447890123456", or "+33678912345")
NO
body string Text message. We auto-detect the encoding needed (GSM 03.38 or UNICODE), or you can force the encoding with options.force_encoding (see the "options" parameter). You always send UTF-8 JSON strings - encoding is done at SMS interconnections level. Depending on the encoding, messages may be split into parts at 153 (GSM) or 67 (UNICODE) characters.

One SMS sent with this method may be billed as multiple SMS parts. You can check the number of parts sent with the method "sms.get".

If you are using a custom sender, you can use the special string %STOPNUM% -- it will be replaced by the STOP number.
NO
options array SMS Options. Omit parameter to use default values. Format in query string: options.key=value.
Object: SMS.Options
YES

Result

Type Description Format/Object
string SMS ID Format: hash (Unique object identifier)

Example request

#!/bin/bash

login='API_LOGIN'
password='API_PASSWORD'

curl -G "https://api.callr.com/rest/v1.1/sms/send" \
--user "$login:$password" \
--data-urlencode from="SMS" \
--data-urlencode to="+447890123456" \
--data-urlencode body="SMS sent with the CALLR REST API." \
;

            

GET /sms/<hash>

Description

Retrieve a specific SMS resource based on its hash

Parameters

Parameter Type Description NULL
hash string Hash of the requested SMS NO

Result

Type Description Format/Object
object SMS SMS object.

Example request

#!/bin/bash

login='API_LOGIN'
password='API_PASSWORD'

curl -G "https://api.callr.com/rest/v1.1/sms/<hash>" \
--user "$login:$password" \
--data-urlencode hash="WWXXYYZZ" \
;