# 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"]}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onomondo.com/readme/sms.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.