Searching for SIMs

In addition to performing SIM management tasks, Soracom provides several methods to quickly locate a SIM (subscriber), simplifying the management of a large number of SIMs.

When searching using the User Console, API, or CLI, please be aware of the following limitations:

  • Search terms must contain at least two characters.
  • Search terms are not case sensitive.
  • Search results will include partial matches as well as exact matches.
  • For multi-value tags, the search API will search all the values and return results of any match.

Searching with the User Console

  1. Login to the User Console. From the main menu, open the SIM Management screen.

  2. Enter a search term into the search box, then press Enter or click the button.

SIM Search

Searching By Attributes

By default, the search will match any of the SIM attributes below. To limit your search to a specific attribute, click the button next to the search box, and select the attribute you want to search.

Select Attribute


Filtering By Status

You can further filter the list according to SIM Status. Click the in the Status column, then change the next to each status to show or hide SIMs with the corresponding status as needed.

Filter Status

Searching with the Soracom API

For programmatic usage, you can perform the same searches using the searchSubscribers API. For details on usage, please refer to the API documentation here.

Searching with the Soracom CLI

You can also perform searches using the Soracom CLI. For instructions on installing the CLI and authenticating your account, please refer to the Soracom CLI documentation.

When using the Soracom CLI, you must specify the attribute. For example, to search for a SIM with name my-sim, run the following command:

soracom query subscribers --name='my-sim'

You can combine multiple parameters to further constrain the search results. For example, to search for a SIM with name my-sim which also belongs to a group my-group, run the following command:

soracom query subscribers --name='my-sim' --group='my-group'

By default, the search will return results that match all of the parameters. To return results that match any of the parameters instead, specify --search-type='or'. The following command will search for SIMs with name my-sim or which belong to a group my-group:

soracom query subscribers --name='my-sim' --group='my-group' --search-type='or'

Controlling SAM User Access

Soracom Access Management (SAM) allows you to provide limited access to your Soracom account without having to share your root account credentials. To allow a SAM user permission to search for subscribers, add a Query:searchSubscribers statement to the SAM User permissions:

  "statements": [
      "api": [
      "effect": "allow"

By granting Query:searchSubscribers to a SAM user, that user will also be able to list (view) all Groups and SIMs. To allow list (view) only without the ability to search, use the Subscriber:listSubscribers rule instead.

For additional information on SAM Users and permissions, refer to the following pages: