---
title: "Change SIM state (batch)"
method: POST
path: "/devices/batch/state"
tags: ["SIMs (Devices)"]
---

# Change SIM state (batch)

`POST /devices/batch/state`

## Request

- Base URL: `https://dashboard.hologram.io/api/1`
- URL: `https://dashboard.hologram.io/api/1/devices/batch/state`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/hologram/apis/hologram-rest-api-v1/docs/devices/batch/state/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a batch job to change the state of a large set of SIMs using the device ID for each SIM. Accepts device IDs directly or a bulk filter criteria. Returns a list of tasks for the batch runner.

## Request body

- union
  - object: Top-level parameters for bulk device selection via BulkSelection. Explicit deviceids are merged with filter-based selection. Some endpoints require a feature flag (e.g. bulk_rename, bulk_tag) before bulk selection is enabled.
    - `deviceids` integer[], required: Explicit list of device IDs to include in the selection.
    - `allSelected` boolean: When true, select all devices in the organization (subject to excludedDeviceIds).
    - `useSearch` boolean: When true, resolve the device selection from the search index using deviceFilters instead of the database.
    - `deviceFilters` DeviceBulkSelectionFilters: Filter criteria for bulk device selection via BulkSelection. When resolved from the database (default), accepts the same filter fields as GET /devices (e.g. states, tagids, planid). When useSearch is true, also accepts search-index filter fields (e.g. links_cur_billing_data_used).
      - `limit` integer: Maximum number of devices per page.
      - `pageIdsSelected` integer[]: Cursor IDs (startafter values) that identify which pages of the device list to include.
      - `pagesSelected` integer[]: Page numbers selected.
      - `states` string[]: Filter devices by state (e.g. LIVE, PAUSED-USER).
      - `hitsPerPage` integer: Number of results per page used to compute page boundaries.
      - `orgid` integer: Organization ID.
      - `query` string: Search query string (used when useSearch is true).
      - `sort` object: Sort field and direction (used when useSearch is true). Example: {"links_cur_billing_data_used": "ASC"}
      - `filters` object: Additional search filter criteria (used when useSearch is true).
    - `excludedDeviceIds` integer[]: Device IDs to exclude from the bulk selection.
    - `pagesSelected` integer[]: Top-level page numbers selected; presence triggers bulk device selection.
    - `state` string, required: New state: pause, live, or deactivate
  - object: Top-level parameters for bulk device selection via BulkSelection. Explicit deviceids are merged with filter-based selection. Some endpoints require a feature flag (e.g. bulk_rename, bulk_tag) before bulk selection is enabled.
    - `deviceids` integer[]: Explicit list of device IDs to include in the selection.
    - `allSelected` boolean: When true, select all devices in the organization (subject to excludedDeviceIds).
    - `useSearch` boolean: When true, resolve the device selection from the search index using deviceFilters instead of the database.
    - `deviceFilters` DeviceBulkSelectionFilters, required: Filter criteria for bulk device selection via BulkSelection. When resolved from the database (default), accepts the same filter fields as GET /devices (e.g. states, tagids, planid). When useSearch is true, also accepts search-index filter fields (e.g. links_cur_billing_data_used).
      - `limit` integer: Maximum number of devices per page.
      - `pageIdsSelected` integer[]: Cursor IDs (startafter values) that identify which pages of the device list to include.
      - `pagesSelected` integer[]: Page numbers selected.
      - `states` string[]: Filter devices by state (e.g. LIVE, PAUSED-USER).
      - `hitsPerPage` integer: Number of results per page used to compute page boundaries.
      - `orgid` integer: Organization ID.
      - `query` string: Search query string (used when useSearch is true).
      - `sort` object: Sort field and direction (used when useSearch is true). Example: {"links_cur_billing_data_used": "ASC"}
      - `filters` object: Additional search filter criteria (used when useSearch is true).
    - `excludedDeviceIds` integer[]: Device IDs to exclude from the bulk selection.
    - `pagesSelected` integer[]: Top-level page numbers selected; presence triggers bulk device selection.
    - `state` string, required: New state: pause, live, or deactivate

## Response `200`

OK

- BatchJobResponse
  - `success` boolean: Indicates whether the request was successful.
  - `data` object
    - `jobid` integer: ID of the created batch job
    - `preview` boolean: Whether this was a preview (dry-run) request
    - `valid_tasks` object[]: List of validated tasks queued in this job

## Other responses

- `400`: Bad request
- `401`: Unauthorized

---

[API](https://skmtc.dev/hologram/apis/hologram-rest-api-v1.md) - [All operations](https://skmtc.dev/hologram/apis/hologram-rest-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/hologram/apis/hologram-rest-api-v1/revisions/1bc07dcd1631?raw)