# SIMs
## Retrieve information for all SIMs
> Returns detailed information for all registered SIMs.\
> \
> {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\
> \
> Minimum package requirement for SIM alert threshold information: \Pro\ {% endhint %}\
> Using parameters will focus the records returned in the response.
```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":{"/sims":{"get":{"summary":"Retrieve information for all SIMs","description":"Returns detailed information for all registered SIMs.\n\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}\nUsing parameters will focus the records returned in the response.","parameters":[{"name":"next_page","in":"query","schema":{"type":"string"},"description":"Used for pagination of records."},{"name":"limit","in":"query","schema":{"type":"string"},"description":"The max number of records returned. Limit can be between 1 and 5000 records. Default is 1000 records."},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter SIMs based on various criteria. Can be provided as a single filter or multiple filters.\n\n**Single filter format**: `filter=key:value`\n\n**Multiple filters format**: `filter[]=key:value&filter[]=key2:value2`\n\nSupported filter types:\n\n**online** - Boolean filter for SIM online status\n- Format: `online:true` or `online:false`\n\n**activated** - Boolean filter for SIM activation status\n- Format: `activated:true` or `activated:false`\n\n**connector** - Filter by Connector name\n- Format: `connector:`\n\n**network_whitelist** - Filter by Network List name\n- Format: `network_whitelist:`\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Retrieve information for a specific SIM
> Returns detailed information for a specific SIM.\
> {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\
> \
> Minimum package requirement for SIM alert threshold information: \Pro\ {% endhint %}\
> By default, we suggest to use the \*\*SIM ID\*\* that can be found on the SIM card itself or from \[SIMs page in the web app]\(
> You can also use the \*\*ICCID value\*\*, if that is available.\
> \
> Note that the \`location\` and \`device\_info\` fields are optional, meaning that they are only present if the information is available.
```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":{"/sims/{sim_id}":{"get":{"summary":"Retrieve information for a specific SIM","description":"Returns detailed information for a specific SIM.\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}\nBy default, we suggest to use the **SIM ID** that can be found on the SIM card itself or from [SIMs page in the web app](https://app.onomondo.com/sims).\nYou can also use the **ICCID value**, if that is available.\n\nNote that the `location` and `device_info` fields are optional, meaning that they are only present if the information is available.","parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Find SIMs
> Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.\
> {% hint style="info" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: \Fleet\\
> \
> Minimum package requirement for SIM alert threshold information: \Pro\ {% 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":{"/sims/find":{"get":{"summary":"Find SIMs","description":"Retrieves a list of SIMs filtered by partial SIM ID, label, or exact ICCID match.\n{% hint style=\"info\" %} Minimum package requirement for SIM location, modem model, and modem manufacturer information: Fleet\n\nMinimum package requirement for SIM alert threshold information: Pro {% endhint %}","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"A partial SIM id or label, as well as a complete ICCID.","required":true},{"name":"limit","in":"query","schema":{"type":"string"},"description":"Without this parameter the default is 10. Limit can be between 1 and 5000 records."},{"name":"offset","in":"query","schema":{"type":"string"},"description":"The number of first records returned. Used for pagination of records, otherwise will default to 0."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Update specific SIM
> Updates configurable parameters for the specified SIM.\
> {% hint style="info" %} Minimum package requirement for updating SIM alert: \Pro\ {% endhint %}\
> This request takes a JSON body. Only the properties that are being updated need to be included.
```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":{"/sims/{sim_id}":{"patch":{"summary":"Update specific SIM","description":"Updates configurable parameters for the specified SIM.\n{% hint style=\"info\" %} Minimum package requirement for updating SIM alert: Pro {% endhint %}\nThis request takes a JSON body. Only the properties that are being updated need to be included.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","nullable":true,"description":"A string alias of the SIM, null if no alias to be assigned."},"network_whitelist":{"type":"string","nullable":true,"description":"Name of the Network List attached, null if no Network List should be attached."},"imei_lock":{"type":"string","nullable":true,"description":"String IMEI of device the SIM should be locked to (if presented in network signaling) or a null value."},"connector":{"type":"string","nullable":true,"description":"Name of Connector attached, set to null if no Connector should be attached."},"activated":{"type":"boolean","description":"Boolean to activate and deactivate the SIM."},"data_limit":{"type":"object","nullable":true,"description":"Object that can set hard data limits to the SIM. When the limit is reached the device will not be able to send data until the time indicated by the property `resets_at`. If webhook is set up, usage-alert events will be triggered at alert_threshold and when total limit is reached.","required":["total","type"],"properties":{"total":{"type":"integer","minimum":500000,"description":"Data limit in bytes (minimum 500KB)."},"type":{"type":"string","enum":["minute","hourly","daily","monthly"],"description":"Time period for the data limit reset."},"alert_threshold":{"type":"integer","minimum":500000,"description":"Warning amount in bytes. Must be less than total. Triggers usage-alert event when reached (minimum 500KB)."}}},"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with a SIM. Tag IDs require string format and can be obtained using GET /tags endpoint. **Caution**: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags."},"technologies":{"type":"object","description":"Object to control technology access. **Caution**: Ensure SIM is not connected to RAN when changing these settings.","properties":{"sms":{"type":"boolean","description":"Set to false to remove the ability to send SMS."},"2g_3g":{"type":"boolean","description":"Set to false to remove the ability to connect on 2G/3G."},"4g":{"type":"boolean","description":"Set to false to remove ability to connect to 4G."}}}}}}}},"parameters":[{"name":"Content-Type","in":"header","schema":{"type":"string"}},{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Bulk SIM Update
> Updates configuration parameters for multiple SIMs simultaneously.\
> \
> {% hint style="info" %} Minimum package requirement for updating SIM alert: \Pro\ {% endhint %}\
> \
> This request takes a JSON body. Only the properties that are being updated needs to be included. All properties that can be updated by a single SIM update can be added to the bulk call.\
> \
> \*\*LIMIT: 20 SIMs per call\*\*\
> \
> \`sims\` is the only one field in the body, which consists of an array of SIM update objects.\
> \
> Each object needs to have the field \`id\`, which is the 9 character SIM ID.\
> \
> {% hint style="warning" %} ICCID is not accepted but can be connected to a SIM ID by taking the first 9 of the last 10 numbers of the ICCID. Here is an ICCID example with the SIM ID in bold:\
> \
> 8945738730-\_\_000001934\_\_-2 {% 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":{"/sims/bulk":{"patch":{"summary":"Bulk SIM Update","description":"Updates configuration parameters for multiple SIMs simultaneously.\n\n{% hint style=\"info\" %} Minimum package requirement for updating SIM alert: Pro {% endhint %}\n\nThis request takes a JSON body. Only the properties that are being updated needs to be included. All properties that can be updated by a single SIM update can be added to the bulk call.\n\n**LIMIT: 20 SIMs per call**\n\n`sims` is the only one field in the body, which consists of an array of SIM update objects.\n\nEach object needs to have the field `id`, which is the 9 character SIM ID.\n\n{% hint style=\"warning\" %} ICCID is not accepted but can be connected to a SIM ID by taking the first 9 of the last 10 numbers of the ICCID. Here is an ICCID example with the SIM ID in bold:\n\n8945738730-__000001934__-2 {% endhint %}","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["sims"],"properties":{"sims":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The SIM ID."},"label":{"type":"string","nullable":true,"description":"A string alias of the SIM, null if no alias to be assigned."},"network_whitelist":{"type":"string","nullable":true,"description":"Name of the Network List attached, null if no Network List should be attached."},"imei_lock":{"type":"string","nullable":true,"description":"String IMEI of device the SIM should be locked to (if presented in network signaling) or a null value."},"connector":{"type":"string","nullable":true,"description":"Name of Connector attached, set to null if no Connector should be attached."},"activated":{"type":"boolean","description":"Boolean to activate and deactivate the SIM."},"data_limit":{"type":"object","nullable":true,"description":"Object that can set hard data limits to the SIM. When the limit is reached the device will not be able to send data until the time indicated by the property `resets_at`. If webhook is set up, usage-alert events will be triggered at alert_threshold and when total limit is reached.","required":["total","type"],"properties":{"total":{"type":"integer","minimum":500000,"description":"Data limit in bytes (minimum 500KB)."},"type":{"type":"string","enum":["minute","hourly","daily","monthly"],"description":"Time period for the data limit reset."},"alert_threshold":{"type":"integer","minimum":500000,"description":"Warning amount in bytes. Must be less than total. Triggers usage-alert event when reached (minimum 500KB)."}}},"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with a SIM. Tag IDs require string format and can be obtained using GET /tags endpoint. **Caution**: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags."},"technologies":{"type":"object","description":"Object to control technology access. **Caution**: Ensure SIM is not connected to RAN when changing these settings.","properties":{"sms":{"type":"boolean","description":"Set to false to remove the ability to send SMS."},"2g/3g":{"type":"boolean","description":"Set to false to remove the ability to connect on 2G/3G."},"4g":{"type":"boolean","description":"Set to false to remove ability to connect to 4G."}}}}}}}}}}},"parameters":[{"name":"Content-Type","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Add Tag to list of Tags of a SIM
> Adds the Tag with the Tag ID to the given SIM. Will throw a \`400\` error if the Tag already is associated with the SIM.
```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":{"/sims/{sim_id}/tags/{tag_id}":{"put":{"summary":"Add Tag to list of Tags of a SIM","description":"Adds the Tag with the Tag ID to the given SIM. Will throw a `400` error if the Tag already is associated with the SIM.","requestBody":{"content":{}},"parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true},{"name":"tag_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Remove Tag from list of Tags of a SIM
> Removes the Tag with Tag ID from the given SIM. Will throw a \`400\` error if the Tag is not currently associated with the SIM.
```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":{"/sims/{sim_id}/tags/{tag_id}":{"delete":{"summary":"Remove Tag from list of Tags of a SIM","description":"Removes the Tag with Tag ID from the given SIM. Will throw a `400` error if the Tag is not currently associated with the SIM.","parameters":[{"name":"sim_id","in":"path","schema":{"type":"string"},"required":true},{"name":"tag_id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
---
# 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/sims.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.