> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hologram.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag SIMs using the REST API

> If you want to tag hundreds, or even thousands of devices, we recommend using our REST API for additional control over how your SIMs are named.

## How to tag multiple SIMs using the REST API

If you want to tag hundreds, or even thousands of devices, we recommend using our [REST API](/api/1/). This option lets you programmatically tag devices. Use the devices/tags endpoints to create a tag, list tag IDs, and link devices to a tag.

If you aren't familiar with APIs, we highly recommend checking out our [introduction to Hologram's REST API guide](/guides/rest-api/beginners-guide-to-the-hologram-rest-api/) as well as using [Postman](https://www.getpostman.com/) to make the API calls mentioned in this guide.

<Note>
  **Note:** You can also make bulk SIM changes [in your dashboard](/dashboard/sim-actions/tag-sims).
</Note>

<Steps>
  <Step title="Create the tag and capture its ID">
    <RequestExample>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://dashboard.hologram.io/api/1/devices/tags' \
        -u apikey:YOUR_HOLOGRAM_API_KEY \
        --header 'Content-Type: application/json' \
        --data-raw '{"name":"YOUR_TAG_NAME"}'
      ```
    </RequestExample>
  </Step>

  <Step title="Look up an existing tag ID (optional)">
    <RequestExample>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://dashboard.hologram.io/api/1/devices/tags' \
        -u apikey:YOUR_HOLOGRAM_API_KEY
      ```
    </RequestExample>
  </Step>

  <Step title="Link devices to your tag">
    <RequestExample>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://dashboard.hologram.io/api/1/devices/tags/YOUR_TAG_ID/link/' \
        -u apikey:YOUR_HOLOGRAM_API_KEY \
        --header 'Content-Type: application/json' \
        --data-raw '{"deviceids":[YOUR_DEVICE_ID_1, YOUR_DEVICE_ID_2, YOUR_DEVICE_ID_N]}'
      ```
    </RequestExample>
  </Step>
</Steps>

<Note>
  **Note:** For tags scoped to a custom organization, include `orgid=YOUR_ORG_ID` where required.
</Note>

***

title: "Tag multiple SIMs using the REST API"
description: "Create tags and link them to many devices using REST API endpoints."
----------------------------------------------------------------------------------

Programmatically tag large fleets using the REST API.

## How do I use the REST API to tag SIMs in bulk?

<Steps>
  <Step title="Create a tag">
    ```http theme={null}
    POST https://dashboard.hologram.io/api/1/devices/tags
    ```

    Body:

    ```json theme={null}
    { "name": "YOUR_TAG_NAME" }
    ```
  </Step>

  <Step title="List tags">
    ```http theme={null}
    GET https://dashboard.hologram.io/api/1/devices/tags
    ```
  </Step>

  <Step title="List devices">
    ```http theme={null}
    GET https://dashboard.hologram.io/api/1/devices
    ```
  </Step>

  <Step title="Link devices to a tag">
    ```http theme={null}
    POST https://dashboard.hologram.io/api/1/devices/tags/{TAG_ID}/link
    ```

    Body:

    ```json theme={null}
    { "deviceids": [DEVICE_ID_1, DEVICE_ID_2] }
    ```
  </Step>
</Steps>

## Related actions

<Card title="Dashboard bulk actions" href="/dashboard/sim-actions/tag-sims" horizontal>
  Tag SIMs in bulk in your dashboard.
</Card>