> ## 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.
# Purchase eSIMs
> Purchases and registers the specified amount of eSIMs to the current user's account.
If sim_card_group_id is provided, the eSIMs will be associated with that group. Otherwise, the default group for the current user will be used.
## OpenAPI
````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/wireless/sim-cards-provisioning.yml post /actions/purchase/esims
openapi: 3.1.0
info:
title: SIM Cards Provisioning API
version: 2.0.0
description: >-
SIM card ordering, registration, and provisioning actions including enable,
disable, and standby.
contact:
email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
security:
- bearerAuth: []
paths:
/actions/purchase/esims:
post:
tags:
- SIM Cards
summary: Purchase eSIMs
description: >
Purchases and registers the specified amount of eSIMs to the current
user's account.
If sim_card_group_id is provided, the eSIMs will be
associated with that group. Otherwise, the default group for the current
user will be used.
operationId: PurchaseESim
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ESimPurchase'
required: true
responses:
'202':
$ref: '#/components/responses/RegisterSimCardsResponse'
'401':
description: Unauthorized
x-codeSamples:
- lang: JavaScript
source: >-
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const purchase = await client.actions.purchase.create({ amount: 10
});
console.log(purchase.data);
- lang: Python
source: |-
import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
purchase = client.actions.purchase.create(
amount=10,
)
print(purchase.data)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpurchase, err := client.Actions.Purchase.New(context.TODO(), telnyx.ActionPurchaseNewParams{\n\t\tAmount: 10,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", purchase.Data)\n}\n"
- lang: Java
source: >-
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.actions.purchase.PurchaseCreateParams;
import
com.telnyx.sdk.models.actions.purchase.PurchaseCreateResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
PurchaseCreateParams params = PurchaseCreateParams.builder()
.amount(10L)
.build();
PurchaseCreateResponse purchase = client.actions().purchase().create(params);
}
}
- lang: Ruby
source: |-
require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
purchase = telnyx.actions.purchase.create(amount: 10)
puts(purchase)
- lang: CLI
source: |-
telnyx actions:purchase create \
--api-key 'My API Key' \
--amount 10
components:
schemas:
ESimPurchase:
title: SIMCardRegistration
type: object
properties:
sim_card_group_id:
type: string
format: uuid
description: >-
The group SIMCardGroup identification. This attribute can be
null when it's present in an associated resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
tags:
type: array
description: Searchable tags associated with the SIM cards
items:
type: string
example:
- personal
- customers
- active-customers
product:
type: string
description: >-
Type of product to be purchased, specify "whitelabel" to use a
custom SPN
example: whitelabel
whitelabel_name:
type: string
description: >-
Service Provider Name (SPN) for the Whitelabel eSIM product. It will
be displayed as the mobile service name by operating systems of
smartphones. This parameter must only contain letters, numbers and
whitespaces.
example: Custom SPN
amount:
type: integer
description: The amount of eSIMs to be purchased.
example: 10
minimum: 1
status:
type: string
description: >-
Status on which the SIM cards will be set after being successfully
registered.
enum:
- enabled
- disabled
- standby
example: standby
default: enabled
required:
- amount
SimpleSIMCard:
type: object
title: SIMCard
properties:
id:
type: string
format: uuid
description: Identifies the resource.
readOnly: true
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
record_type:
type: string
example: sim_card
readOnly: true
status:
$ref: '#/components/schemas/SIMCardStatus'
type:
type: string
description: The type of SIM card
readOnly: true
example: physical
enum:
- physical
- esim
iccid:
type: string
description: >
The ICCID is the identifier of the specific SIM card/chip. Each SIM
is internationally identified by its integrated circuit card
identifier (ICCID). ICCIDs are stored in the SIM card's memory and
are also engraved or printed on the SIM card body during a process
called personalization.
readOnly: true
example: '89310410106543789301'
imsi:
type: string
description: >
SIM cards are identified on their individual network operators by a
unique International Mobile Subscriber Identity (IMSI).
Mobile network operators connect mobile phone calls and communicate
with their market SIM cards using their IMSIs. The IMSI is stored in
the Subscriber Identity Module (SIM) inside the device and is sent
by the device to the appropriate network. It is used to acquire the
details of the device in the Home Location Register (HLR) or the
Visitor Location Register (VLR).
readOnly: true
example: '081932214823362973'
msisdn:
type: string
description: >
Mobile Station International Subscriber Directory Number (MSISDN) is
a number used to identify a mobile phone number internationally.
MSISDN is defined by the E.164 numbering plan. It includes a country
code and a National Destination Code which identifies the
subscriber's operator.
readOnly: true
example: '+13109976224'
sim_card_group_id:
type: string
format: uuid
description: >-
The group SIMCardGroup identification. This attribute can be
null when it's present in an associated resource.
example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
tags:
type: array
description: Searchable tags associated with the SIM card
items:
type: string
example:
- personal
- customers
- active-customers
data_limit:
type: object
description: The SIM card individual data limit configuration.
readOnly: true
properties:
amount:
type: string
example: '2048.0'
unit:
type: string
example: MB
enum:
- MB
- GB
current_billing_period_consumed_data:
type: object
description: The SIM card consumption so far in the current billing cycle.
readOnly: true
properties:
amount:
type: string
example: '2049.0'
unit:
type: string
example: MB
default: MB
actions_in_progress:
type: boolean
description: Indicate whether the SIM card has any pending (in-progress) actions.
readOnly: true
example: true
default: false
created_at:
type: string
description: >-
ISO 8601 formatted date-time indicating when the resource was
created.
readOnly: true
example: '2018-02-02T22:25:27.521Z'
updated_at:
type: string
description: >-
ISO 8601 formatted date-time indicating when the resource was
updated.
readOnly: true
example: '2018-02-02T22:25:27.521Z'
esim_installation_status:
type:
- string
- 'null'
description: The installation status of the eSIM. Only applicable for eSIM cards.
readOnly: true
example: released
enum:
- released
- disabled
version:
type: string
description: The version of the SIM card.
readOnly: true
example: '4.3'
resources_with_in_progress_actions:
type: array
description: List of resources with actions in progress.
readOnly: true
items:
type: object
example: []
eid:
type:
- string
- 'null'
description: The Embedded Identity Document (eID) for eSIM cards.
readOnly: true
example: null
authorized_imeis:
type:
- array
- 'null'
description: List of IMEIs authorized to use a given SIM card.
items:
type: string
example:
- '106516771852751'
- '534051870479563'
- '508821468377961'
voice_enabled:
type: boolean
description: Indicates whether voice services are enabled for the SIM card.
readOnly: true
example: false
default: false
wireless_Error:
required:
- code
- title
properties:
code:
type: string
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
parameter:
description: Indicates which query parameter caused the error.
type: string
meta:
type: object
additionalProperties: true
type: object
SIMCardStatus:
type: object
properties:
value:
type: string
enum:
- registering
- enabling
- enabled
- disabling
- disabled
- data_limit_exceeded
- setting_standby
- standby
description: >
The current status of the SIM card. It will be one of the following:
registering - the card is being registeredenabling - the card is being enabledenabled - the card is enabled and ready for usedisabling - the card is being disableddisabled - the card has been disabled and cannot be useddata_limit_exceeded - the card has exceeded its data consumption limitsetting_standby - the process to set the card in stand by is in progressstandby - the card is in stand by
Transitioning between the enabled and disabled states may take a
period of time.
readOnly: true
example: enabled
reason:
type: string
description: It describes why the SIM card is in the current status.
readOnly: true
example: >-
The SIM card is active, ready to connect to networks and consume
data.
responses:
RegisterSimCardsResponse:
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
description: Successfully registered SIM cards.
type: array
items:
$ref: '#/components/schemas/SimpleSIMCard'
errors:
type: array
items:
$ref: '#/components/schemas/wireless_Error'
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````