OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens SIM Card Groups API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: SIM Card Groups operations
name: SIM Card Groups
paths:
/sim_card_groups:
get:
description: Get all SIM card groups belonging to the user that match the given filters.
operationId: GetAllSimCardGroups
parameters:
- $ref: '#/components/parameters/wireless_PageNumber'
- $ref: '#/components/parameters/wireless_PageSize'
- description: A valid SIM card group name.
in: query
name: filter[name]
schema:
example: My Test Group
type: string
- description: A Private Wireless Gateway ID associated with the group.
in: query
name: filter[private_wireless_gateway_id]
schema:
example: 7606c6d3-ff7c-49c1-943d-68879e9d584d
format: uuid
type: string
- description: A Wireless Blocklist ID associated with the group.
in: query
name: filter[wireless_blocklist_id]
schema:
example: 0f3f490e-c4d3-4cf5-838a-9970f10ee259
format: uuid
type: string
responses:
'200':
$ref: '#/components/responses/GetAllSimCardGroupsResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Get all SIM card groups
tags:
- SIM Card Groups
x-latency-category: responsive
post:
description: Creates a new SIM card group object
operationId: CreateSimCardGroup
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SIMCardGroupCreate'
required: true
responses:
'200':
$ref: '#/components/responses/CreateSimCardGroupResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Create a SIM card group
tags:
- SIM Card Groups
x-latency-category: responsive
/sim_card_groups/{id}:
delete:
description: Permanently deletes a SIM card group
operationId: DeleteSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
responses:
'200':
$ref: '#/components/responses/DeleteSimCardGroupResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Delete a SIM card group
tags:
- SIM Card Groups
x-latency-category: responsive
get:
description: Returns the details regarding a specific SIM card group
operationId: GetSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
- $ref: '#/components/parameters/IncludeICCIDs'
responses:
'200':
$ref: '#/components/responses/GetSimCardGroupResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Get SIM card group
tags:
- SIM Card Groups
x-latency-category: responsive
patch:
description: Updates a SIM card group
operationId: UpdateSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SIMCardGroupPatch'
required: true
responses:
'200':
$ref: '#/components/responses/UpdateSimCardGroupResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Update a SIM card group
tags:
- SIM Card Groups
x-latency-category: responsive
/sim_card_groups/{id}/actions/remove_private_wireless_gateway:
post:
description: This action will asynchronously remove an existing Private Wireless Gateway definition from a SIM card group. Completing this operation defines that all SIM cards in the SIM card group will get their traffic handled by Telnyx's default mobile network configuration.
operationId: RemoveSimCardGroupPrivateWirelessGateway
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
responses:
'202':
$ref: '#/components/responses/SIMCardGroupActionResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Request Private Wireless Gateway removal from SIM card group
tags:
- SIM Card Groups
x-latency-category: background
/sim_card_groups/{id}/actions/remove_wireless_blocklist:
post:
description: This action will asynchronously remove an existing Wireless Blocklist to all the SIMs in the SIM card group.
operationId: RemoveWirelessBlocklistForSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
responses:
'202':
$ref: '#/components/responses/SIMCardGroupActionResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Request Wireless Blocklist removal from SIM card group
tags:
- SIM Card Groups
x-latency-category: background
/sim_card_groups/{id}/actions/set_private_wireless_gateway:
post:
description: This action will asynchronously assign a provisioned Private Wireless Gateway to the SIM card group. Completing this operation defines that all SIM cards in the SIM card group will get their traffic controlled by the associated Private Wireless Gateway. This operation will also imply that new SIM cards assigned to a group will inherit its network definitions. If it's moved to a different group that doesn't have a Private Wireless Gateway, it'll use Telnyx's default mobile network configuration.
operationId: SetPrivateWirelessGatewayForSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
requestBody:
content:
application/json:
schema:
properties:
private_wireless_gateway_id:
description: The identification of the related Private Wireless Gateway resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
required:
- private_wireless_gateway_id
type: object
required: true
responses:
'202':
$ref: '#/components/responses/SIMCardGroupActionResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Request Private Wireless Gateway assignment for SIM card group
tags:
- SIM Card Groups
x-latency-category: background
/sim_card_groups/{id}/actions/set_wireless_blocklist:
post:
description: This action will asynchronously assign a Wireless Blocklist to all the SIMs in the SIM card group.
operationId: SetWirelessBlocklistForSimCardGroup
parameters:
- $ref: '#/components/parameters/SIMCardGroupId'
requestBody:
content:
application/json:
schema:
properties:
wireless_blocklist_id:
description: The identification of the related Wireless Blocklist resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
required:
- wireless_blocklist_id
type: object
required: true
responses:
'202':
$ref: '#/components/responses/SIMCardGroupActionResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Request Wireless Blocklist assignment for SIM card group
tags:
- SIM Card Groups
x-latency-category: background
components:
schemas:
ConsumedData:
description: Represents the amount of data consumed.
properties:
amount:
example: '2048.1'
type: string
unit:
default: MB
example: MB
type: string
title: ConsumedData
type: object
SearchedSIMCardGroup:
properties:
consumed_data:
$ref: '#/components/schemas/ConsumedData'
created_at:
description: ISO 8601 formatted date-time indicating when the resource was created.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
data_limit:
description: Upper limit on the amount of data the SIM cards, within the group, can use.
properties:
amount:
example: '2048.1'
type: string
unit:
example: MB
type: string
type: object
default:
description: Indicates whether the SIM card group is the users default group.<br/>The default group is created for the user and can not be removed.
example: true
readOnly: true
type: boolean
id:
description: Identifies the resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
readOnly: true
type: string
name:
description: A user friendly name for the SIM card group.
example: My Test Group
type: string
private_wireless_gateway_id:
default: null
description: The identification of the related Private Wireless Gateway resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
record_type:
description: Identifies the type of the resource.
example: sim_card_group
readOnly: true
type: string
sim_card_count:
default: 0
description: The number of SIM cards associated with the group.
example: 10
type: integer
updated_at:
description: ISO 8601 formatted date-time indicating when the resource was updated.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
wireless_blocklist_id:
default: null
description: The identification of the related Wireless Blocklist resource.
example: 5aa584f6-14b1-41b2-8e01-1c04d1ee77c1
format: uuid
type: string
title: SIMCardGroup
type: object
SIMCardGroupPatch:
properties:
data_limit:
description: Upper limit on the amount of data the SIM cards, within the group, can use.
properties:
amount:
example: '2048.1'
type: string
unit:
example: MB
type: string
type: object
name:
description: A user friendly name for the SIM card group.
example: My Test Group
type: string
title: SIMCardGroupPatch
type: object
SIMCardGroupAction:
description: This object represents a SIM card group action request. It allows tracking the current status of an operation that impacts the SIM card group and SIM card in it.
properties:
created_at:
description: ISO 8601 formatted date-time indicating when the resource was created.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
id:
description: Identifies the resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
readOnly: true
type: string
record_type:
example: sim_card_group_action
readOnly: true
type: string
settings:
description: A JSON object representation of the action params.
properties:
private_wireless_gateway_id:
description: The identification of the related Private Wireless Gateway resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
type: object
sim_card_group_id:
description: The SIM card group identification.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
status:
enum:
- in-progress
- completed
- failed
example: in-progress
type: string
type:
description: Represents the type of the operation requested.
enum:
- set_private_wireless_gateway
- remove_private_wireless_gateway
- set_wireless_blocklist
- remove_wireless_blocklist
example: set_private_wireless_gateway
type: string
updated_at:
description: ISO 8601 formatted date-time indicating when the resource was updated.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
title: SIMCardGroupAction
type: object
wireless_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/wireless_Error'
type: array
type: object
wireless_Error:
properties:
code:
type: string
detail:
type: string
meta:
additionalProperties: true
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
type: object
title:
type: string
required:
- code
- title
type: object
SIMCardGroupCreate:
properties:
data_limit:
description: Upper limit on the amount of data the SIM cards, within the group, can use.
properties:
amount:
example: '2048.1'
type: string
unit:
example: MB
type: string
type: object
name:
description: A user friendly name for the SIM card group.
example: My Test Group
type: string
required:
- name
title: SIMCardGroupCreate
type: object
SIMCardGroup:
properties:
consumed_data:
$ref: '#/components/schemas/ConsumedData'
created_at:
description: ISO 8601 formatted date-time indicating when the resource was created.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
data_limit:
description: Upper limit on the amount of data the SIM cards, within the group, can use.
properties:
amount:
example: '2048.1'
type: string
unit:
example: MB
type: string
type: object
default:
description: Indicates whether the SIM card group is the users default group.<br/>The default group is created for the user and can not be removed.
example: true
readOnly: true
type: boolean
id:
description: Identifies the resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
readOnly: true
type: string
name:
description: A user friendly name for the SIM card group.
example: My Test Group
type: string
private_wireless_gateway_id:
default: null
description: The identification of the related Private Wireless Gateway resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
record_type:
description: Identifies the type of the resource.
example: sim_card_group
readOnly: true
type: string
updated_at:
description: ISO 8601 formatted date-time indicating when the resource was updated.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
wireless_blocklist_id:
default: null
description: The identification of the related Wireless Blocklist resource.
example: a13bc415-7966-43bf-90d4-63cc76275289
format: uuid
type: string
title: SIMCardGroup
type: object
PaginationMeta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
type: object
parameters:
IncludeICCIDs:
description: It includes a list of associated ICCIDs.
in: query
name: include_iccids
schema:
default: false
example: true
type: boolean
SIMCardGroupId:
description: Identifies the SIM group.
in: path
name: id
required: true
schema:
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
wireless_PageSize:
description: The size of the page.
in: query
name: page[size]
schema:
default: 20
maximum: 250
minimum: 1
type: integer
wireless_PageNumber:
description: The page number to load.
in: query
name: page[number]
schema:
default: 1
minimum: 1
type: integer
responses:
GetSimCardGroupResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardGroup'
type: object
description: Successful Response
GetAllSimCardGroupsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/SearchedSIMCardGroup'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Successful Response
UpdateSimCardGroupResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardGroup'
type: object
description: Successful Response
CreateSimCardGroupResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardGroup'
type: object
description: Successful Response
wireless_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/wireless_Errors'
description: Unexpected error
SIMCardGroupActionResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardGroupAction'
type: object
description: Successful Response
DeleteSimCardGroupResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardGroup'
type: object
description: Successful Response
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http