Blocklists

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:

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 with the required type query parameter:

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 with a name, the selected type, and its values:

{
  "name": "Blocked countries",
  "type": "country",
  "values": ["CA", "US"]
}

The API returns 201 Created with the new blocklist:

{
  "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, using the SIM Card Group ID in the path:

{
  "wireless_blocklist_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
}

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

{
  "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} 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.

Configuration

Roaming Control

Monitoring & Troubleshooting

Device Guides

For AI Agents

Choose the Blocking Granularity

How Blocklists Combine

Workflow

1. List Valid Values

2. Create the Blocklist

3. Assign the Blocklist

4. Confirm the Assignment

​Choose the Blocking Granularity

​How Blocklists Combine

​Workflow

​1. List Valid Values

​2. Create the Blocklist

​3. Assign the Blocklist

​4. Confirm the Assignment

Choose the Blocking Granularity

How Blocklists Combine

Workflow

1. List Valid Values

2. Create the Blocklist

3. Assign the Blocklist

4. Confirm the Assignment