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

# Blocklists

> Prevent SIMs from connecting to specific networks by country, MCC, or PLMN.

Blocklists restrict which networks a SIM can attach to. Assign a blocklist to a SIM Card Group and every SIM in that group is blocked from the listed networks.

A SIM Card Group can have one blocklist assigned.

## Choose the Blocking Granularity

The blocklist `type` determines how each value is resolved into blocked networks. All values in a blocklist must use the same type.

| Type      | Effect                                                                                                |
| :-------- | :---------------------------------------------------------------------------------------------------- |
| `country` | Blocks every PLMN associated with the selected country in the Telnyx operator dataset.                |
| `mcc`     | Blocks every PLMN whose MCC matches the selected Mobile Country Code in the Telnyx operator dataset.  |
| `plmn`    | Blocks only the selected PLMN, identified by its exact MCC and MNC. This is the most granular option. |

## How Blocklists Combine

Three blocklist scopes can apply to an IMSI:

| Scope            | Applies To                           | Control                                     |
| :--------------- | :----------------------------------- | :------------------------------------------ |
| Global           | Every IMSI on the Telnyx platform    | Managed by Telnyx                           |
| Roaming Platform | Every IMSI roaming on that platform  | Managed by Telnyx                           |
| SIM Card Group   | Every IMSI on every SIM in the group | Managed through the Wireless Blocklists API |

A SIM typically contains five IMSIs, each able to roam on a specific roaming platform. Global and roaming-platform blocklists are visible to users, but cannot be modified. They are not currently exposed through the API.

The effective blocklist for an IMSI is the union of all three scopes:

```text theme={null}
effective blocklist = global ∪ roaming platform ∪ SIM Card Group
```

A network is blocked if it appears in any applicable blocklist. Removing a value from a SIM Card Group blocklist does not allow that network if it remains on the global or roaming-platform blocklist.

## Workflow

### 1. List Valid Values

Call [`GET /wireless_blocklist_values`](/api-reference/wireless-blocklists/get-all-possible-wireless-blocklist-values) with the required `type` query parameter:

```http theme={null}
GET /v2/wireless_blocklist_values?type=country
```

The response field depends on the requested type:

| `type`    | Response Field | Format                                           |
| :-------- | :------------- | :----------------------------------------------- |
| `country` | `country_code` | ISO 3166-1 alpha-2 code, such as `US`            |
| `mcc`     | `mcc`          | Three-digit Mobile Country Code, such as `310`   |
| `plmn`    | `plmn`         | Five- or six-digit MCC and MNC, such as `310260` |

Use values returned for the selected type. Do not mix value types in one blocklist.

### 2. Create the Blocklist

Send [`POST /wireless_blocklists`](/api-reference/wireless-blocklists/create-a-wireless-blocklist) with a name, the selected type, and its values:

```json theme={null}
{
  "name": "Blocked countries",
  "type": "country",
  "values": ["CA", "US"]
}
```

The API returns `201 Created` with the new blocklist:

```json theme={null}
{
  "data": {
    "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "created_at": "2018-02-02T22:25:27.521Z",
    "updated_at": "2018-02-02T22:25:27.521Z",
    "name": "Blocked countries",
    "type": "country",
    "values": ["CA", "US"]
  }
}
```

The `id` in the response is the blocklist ID. Use it as the `wireless_blocklist_id` when assigning the blocklist to a SIM Card Group.

### 3. Assign the Blocklist

Send [`POST /sim_card_groups/{id}/actions/set_wireless_blocklist`](/api-reference/sim-card-groups/request-wireless-blocklist-assignment-for-sim-card-group), using the SIM Card Group ID in the path:

```json theme={null}
{
  "wireless_blocklist_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
}
```

The API returns `202 Accepted` with a SIM Card Group action:

```json theme={null}
{
  "data": {
    "id": "2ab5bd08-13b0-4a6c-aaf0-c565a2603baf",
    "status": "in-progress",
    "type": "set_wireless_blocklist",
    "record_type": "sim_card_group_action",
    "updated_at": "2026-08-13T19:03:51Z",
    "settings": {
      "wireless_blocklist_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
    },
    "created_at": "2026-08-13T19:03:51Z",
    "sim_card_group_id": "55731d76-2cde-4dc1-975b-a3b74a48e137"
  }
}
```

The `id` in this response is the action ID. A status of `in-progress` means the blocklist assignment has not completed.

### 4. Confirm the Assignment

Poll [`GET /sim_card_group_actions/{id}`](/api-reference/sim-card-group-actions/get-sim-card-group-action-details) with the action ID until the status is `completed`.

* `in-progress`: continue polling.
* `completed`: the blocklist is assigned to the group.

After the action completes, all SIMs in the group inherit the blocklist.