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 Orders 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 Orders operations
name: SIM Card Orders
paths:
/sim_card_order_preview:
post:
description: Preview SIM card order purchases.
operationId: PreviewSimCardOrders
requestBody:
content:
application/json:
schema:
properties:
address_id:
description: Uniquely identifies the address for the order.
example: '1293384261075731499'
type: string
quantity:
description: The amount of SIM cards that the user would like to purchase in the SIM card order.
example: 21
minimum: 1
type: integer
required:
- quantity
- address_id
type: object
responses:
'202':
$ref: '#/components/responses/SIMCardOrdersPreviewResponse'
'422':
$ref: '#/components/responses/wireless_UnprocessableEntity'
summary: Preview SIM card orders
tags:
- SIM Card Orders
x-latency-category: responsive
/sim_card_orders:
get:
description: Get all SIM card orders according to filters.
operationId: GetSimCardOrders
parameters:
- $ref: '#/components/parameters/FilterSIMCardOrdersConsolidated'
- $ref: '#/components/parameters/wireless_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/GetAllSimCardOrdersResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Get all SIM card orders
tags:
- SIM Card Orders
x-latency-category: responsive
post:
description: Creates a new order for SIM cards.
operationId: CreateSimCardOrder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimCardOrderCreate'
required: true
responses:
'200':
$ref: '#/components/responses/CreateSimCardOrderResponse'
'401':
description: Unauthorized
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Create a SIM card order
tags:
- SIM Card Orders
x-latency-category: responsive
/sim_card_orders/{id}:
get:
description: Get a single SIM card order by its ID.
operationId: GetSimCardOrder
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
$ref: '#/components/responses/GetSimCardOrderResponse'
'404':
$ref: '#/components/responses/wireless_ResourceNotFound'
default:
$ref: '#/components/responses/wireless_GenericErrorResponse'
summary: Get a single SIM card order
tags:
- SIM Card Orders
x-latency-category: responsive
components:
responses:
GetSimCardOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardOrder'
type: object
description: Successful Response
CreateSimCardOrderResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardOrder'
type: object
description: Successful Response
wireless_ResourceNotFound:
content:
application/json:
schema:
$ref: '#/components/schemas/wireless_Error'
description: Resource not found
GetAllSimCardOrdersResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/SIMCardOrder'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
type: object
description: Successful Response
SIMCardOrdersPreviewResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/SIMCardOrderPreview'
type: object
description: Successful Response
wireless_UnprocessableEntity:
content:
application/json:
schema:
$ref: '#/components/schemas/wireless_Errors'
description: Unprocessable entity. Check the 'detail' field in response for details.
wireless_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/wireless_Errors'
description: Unexpected error
schemas:
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
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
SimCardOrderCreate:
properties:
address_id:
description: Uniquely identifies the address for the order.
example: '1293384261075731499'
type: string
quantity:
description: The amount of SIM cards to order.
example: 23
minimum: 1
type: integer
required:
- address_id
- quantity
title: SimCardOrderCreate
type: object
SIMCardOrder:
properties:
cost:
description: An object representing the total cost of the order.
example:
amount: '2.52'
currency: USD
properties:
amount:
description: A string representing the cost amount.
example: '2.32'
type: string
currency:
description: Filter by ISO 4217 currency string.
example: USD
type: string
type: object
created_at:
description: ISO 8601 formatted date-time indicating when the resource was last 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
order_address:
description: An object representing the address information from when the order was submitted.
example:
administrative_area: TX
country_code: US
extended_address: 14th Floor
id: '1293384261075731499'
locality: Austin
postal_code: '78701'
street_address: 600 Congress Avenue
properties:
administrative_area:
description: State or province where the address is located.
example: TX
type: string
business_name:
description: The name of the business where the address is located.
example: Telnyx LLC
type: string
country_code:
description: The mobile operator two-character (ISO 3166-1 alpha-2) origin country code.
example: US
type: string
extended_address:
description: Supplemental field for address information.
example: 14th Floor
type: string
first_name:
description: The first name of the shipping recipient.
example: John
type: string
id:
description: Uniquely identifies the address for the order.
example: '1293384261075731499'
type: string
last_name:
description: The last name of the shipping recipient.
example: Smith
type: string
locality:
description: The name of the city where the address is located.
example: Austin
type: string
postal_code:
description: Postal code for the address.
example: '78701'
type: string
street_address:
description: The name of the street where the address is located.
example: 600 Congress Avenue
type: string
readOnly: true
type: object
quantity:
description: The amount of SIM cards requested in the SIM card order.
example: 21
minimum: 1
type: integer
record_type:
description: Identifies the type of the resource.
example: sim_card_order
readOnly: true
type: string
status:
description: The current status of the SIM Card order.<ul> <li><code>pending</code> - the order is waiting to be processed.</li> <li><code>processing</code> - the order is currently being processed.</li> <li><code>ready_to_ship</code> - the order is ready to be shipped to the specified <b>address</b>.</li> <li><code>shipped</code> - the order was shipped and is on its way to be delivered to the specified <b>address</b>.</li> <li><code>delivered</code> - the order was delivered to the specified <b>address</b>.</li> <li><code>canceled</code> - the order was canceled.</li> </ul>
enum:
- pending
- processing
- ready_to_ship
- shipped
- delivered
- canceled
example: pending
type: string
tracking_url:
description: The URL used to get tracking information about the order.
example: http://www.example.com/
format: uri
type: string
updated_at:
description: ISO 8601 formatted date-time indicating when the resource was last updated.
example: '2018-02-02T22:25:27.521Z'
readOnly: true
type: string
title: SIMCardOrder
type: object
SIMCardOrderPreview:
properties:
quantity:
description: The amount of SIM cards requested in the SIM card order.
example: 21
type: integer
record_type:
description: Identifies the type of the resource.
example: sim_card_order_preview
readOnly: true
type: string
shipping_cost:
properties:
amount:
description: A string representing the cost amount.
example: '2.32'
type: string
currency:
description: ISO 4217 currency string.
example: USD
type: string
type: object
sim_cards_cost:
properties:
amount:
description: A string representing the cost amount.
example: '2.32'
type: string
currency:
description: ISO 4217 currency string.
example: USD
type: string
type: object
total_cost:
properties:
amount:
description: A string representing the cost amount.
example: '2.32'
type: string
currency:
description: ISO 4217 currency string.
example: USD
type: string
type: object
title: SIMCardOrderPreview
type: object
parameters:
ResourceId:
description: Identifies the resource.
in: path
name: id
required: true
schema:
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
format: uuid
type: string
wireless_PageConsolidated:
description: 'Consolidated pagination parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
number:
default: 1
description: The page number to load.
minimum: 1
type: integer
size:
default: 20
description: The size of the page.
maximum: 250
minimum: 1
type: integer
type: object
FilterSIMCardOrdersConsolidated:
description: 'Consolidated filter parameter for SIM card orders (deepObject style). Originally: filter[created_at], filter[updated_at], filter[quantity], filter[cost.amount], filter[cost.currency], filter[address.id], filter[address.street_address], filter[address.extended_address], filter[address.locality], filter[address.administrative_area], filter[address.country_code], filter[address.postal_code]'
explode: true
in: query
name: filter
schema:
properties:
address.administrative_area:
description: Filter by state or province where the address is located.
example: TX
type: string
address.country_code:
description: Filter by the mobile operator two-character (ISO 3166-1 alpha-2) origin country code.
example: US
type: string
address.extended_address:
description: Returns entries with matching name of the supplemental field for address information.
example: 14th Floor
type: string
address.id:
description: Uniquely identifies the address for the order.
example: '1293384261075731499'
type: string
address.locality:
description: Filter by the name of the city where the address is located.
example: Austin
type: string
address.postal_code:
description: Filter by postal code for the address.
example: '78701'
type: string
address.street_address:
description: Returns entries with matching name of the street where the address is located.
example: 600 Congress Avenue
type: string
cost.amount:
description: The total monetary amount of the order.
example: '2.53'
type: string
cost.currency:
description: Filter by ISO 4217 currency string.
example: USD
type: string
created_at:
description: Filter by ISO 8601 formatted date-time string matching resource creation date-time.
example: '2018-02-02T22:25:27.521Z'
format: date-time
type: string
quantity:
description: Filter orders by how many SIM cards were ordered.
example: 21
type: integer
updated_at:
description: Filter by ISO 8601 formatted date-time string matching resource last update date-time.
example: '2018-02-02T22:25:27.521Z'
format: date-time
type: string
type: object
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