> For the complete documentation index, see [llms.txt](https://docs.onomondo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onomondo.com/readme/sms.md).
# SMS
## Retrieve SMS usage for all SIMs
> Retrieves all usage information for SMS messages sent to and from devices across all SIMs. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\
> {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/usage/":{"get":{"summary":"Retrieve SMS usage for all SIMs","description":"Retrieves all usage information for SMS messages sent to and from devices across all SIMs. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"limit","in":"query","description":"Maximum number of SMS records to return","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"timestamp","in":"query","description":"Filter SMS records by ISO date (YYYY-MM-DD format)","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"order","in":"query","description":"Temporal sort order for the results","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique SMS record identifier"},"sim_id":{"type":"string","description":"SIM ID associated with the SMS"},"message":{"type":"string","description":"SMS content"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Whether SMS was sent to or from device"},"status":{"type":"string","enum":["delivered","failed","pending"],"description":"Delivery status"},"attempts":{"type":"integer","description":"Number of delivery attempts"},"timestamp":{"type":"string","format":"date-time","description":"When the SMS was processed"}}}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}}}}}
```
## Retrieve SMS usage for a specific SIM
> Retrieve all usage information for SMS messages sent to and from a specific device using its SIM ID. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\
> {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/usage/{sim_id}":{"get":{"summary":"Retrieve SMS usage for a specific SIM","description":"Retrieve all usage information for SMS messages sent to and from a specific device using its SIM ID. The response includes delivery status, attempt counts, and other usage metrics to help track SMS communication with your devices.\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"sim_id","in":"path","required":true,"description":"SIM ID","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of SMS records to return","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"offset","in":"query","description":"Number of records to skip (for pagination)","schema":{"type":"integer","minimum":0,"default":0}},{"name":"timestamp","in":"query","description":"Filter SMS records by ISO date (YYYY-MM-DD format)","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"order","in":"query","description":"Temporal sort order for the results","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time","description":"Timestamp when the SMS was processed"},"sim_id":{"type":"string","description":"SIM ID associated with the SMS"},"iccid":{"type":"string","description":"Integrated Circuit Card Identifier"},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"Direction of the SMS"},"status":{"type":"string","enum":["success","failed","pending"],"description":"SMS delivery status"},"retries_left":{"type":"integer","description":"Number of retry attempts remaining"},"id":{"type":"string","format":"uuid","description":"Unique SMS record identifier"},"session_id":{"type":"string","format":"uuid","description":"Session identifier for the SMS transaction"},"network":{"type":"object","description":"Network information","properties":{"mcc":{"type":"string","description":"Mobile Country Code"},"mnc":{"type":"string","description":"Mobile Network Code"}},"required":["mcc","mnc"]}},"required":["time","sim_id","iccid","direction","status","retries_left","id","session_id","network"]}},"pagination":{"type":"object","properties":{"count":{"type":"integer","description":"Number of records in current response"},"limit":{"type":"integer","description":"Maximum number of records requested"},"offset":{"type":"integer","description":"Number of records skipped"},"total":{"type":"integer","description":"Total number of records available"}},"required":["count","limit","offset","total"]}},"required":["data","pagination"]}}}}}}}}}
```
## Send SMS to a device
> Send SMS messages to a device using its SIM ID. Supports both text and binary SMS with different encoding options.\
> \
> \*\*SMS Types:\*\*\
> \- \*\*Text SMS\*\*: Standard text messages (default)\
> \- \*\*Binary SMS\*\*: Raw binary data with hex or base64 encoding\
> \
> For more information on the difference read \[How to send SMS using the Onomondo web app]\(
> {% hint style="info" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see \this](https://help.onomondo.com/en/articles/161795-where-can-i-see-sms-sent-by-my-device">this) article\ for more information. {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/sms/{sim_id}":{"post":{"summary":"Send SMS to a device","description":"Send SMS messages to a device using its SIM ID. Supports both text and binary SMS with different encoding options.\n\n**SMS Types:**\n- **Text SMS**: Standard text messages (default)\n- **Binary SMS**: Raw binary data with hex or base64 encoding\n\nFor more information on the difference read [How to send SMS using the Onomondo web app](https://help.onomondo.com/en/articles/143654-how-do-i-send-sms-to-a-device-using-the-onomondo-platform).\n{% hint style=\"info\" %} The response does not contain the actual payload/content of the SMSs, in order to get this information you will have to set up a Webhook endpoint or use the web app, see this article for more information. {% endhint %}","parameters":[{"name":"sim_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","text"],"properties":{"from":{"oneOf":[{"type":"integer","minimum":0,"maximum":999999999999999,"description":"Numeric sender ID (up to 15 digits)"},{"type":"string","pattern":"^[a-zA-Z0-9]{1,10}$","description":"Alphanumeric sender ID (1-10 characters, letters and numbers only)"}],"description":"Sender identification - either numeric (up to 15 digits) or alphanumeric (up to 10 chars)"},"type":{"type":"string","enum":["text","binary"],"default":"text","description":"Type of SMS message"},"encoding":{"type":"string","enum":["hex","base64"],"description":"Encoding format for binary SMS (required when type is 'binary')"},"text":{"type":"string","description":"Message content. For text SMS, this is the actual message. For binary SMS, this is the encoded data (hex or base64)."}},"allOf":[{"if":{"properties":{"type":{"const":"binary"}}},"then":{"required":["encoding"],"properties":{"encoding":{"type":"string","enum":["hex","base64"]}}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}}}}
```