SIM Cards

SIM Cards operations

Get all SIM cards

Get all SIM cards belonging to the user that match the given filters.

SecuritybearerAuth

Request

query Parameters

page[number]	integer >= 1 Default: 1 The page number to load
page[size]	integer [ 1 .. 250 ] Default: 20 The size of the page
include_sim_card_group	boolean Default: false It includes the associated SIM card group object in the response when present. Example: include_sim_card_group=true
filter[sim_card_group_id]	string <uuid> A valid SIM card group ID. Example: filter[sim_card_group_id]=47a1c2b0-cc7b-4ab1-bb98-b33fb0fc61b9
filter[tags]	Array of strings A list of SIM card tags to filter on. If the SIM card contains *all* of the given `tags` they will be found. For example, if the SIM cards have the following tags: `['customers', 'staff', 'test']` `['test']` `['customers']` Searching for `['customers', 'test']` returns only the first because it's the only one with both tags. Searching for `test` returns the first two SIMs, because both of them have such tag. Searching for `customers` returns the first and last SIMs. Example: filter[tags]=personal&filter[tags]=customers&filter[tags]=active-customers
filter[iccid]	string A search string to partially match for the SIM card's ICCID. Example: filter[iccid]=89310410106543789301
filter[status]	Array of strings Filter by a SIM card's status. Items Enum: "enabled" "disabled" "standby" "data_limit_exceeded" "unauthorized_imei"
sort	string Sorts SIM cards by the given field. Defaults to ascending order unless field is prefixed with a minus sign. Value: "current_billing_period_consumed_data.amount" Example: sort=-current_billing_period_consumed_data.amount

Responses

200

Successful response

Response Schema: application/json

	Array of objects (SIMCard)
	object (PaginationMeta)

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards

Request samples

Response samples

200
default

application/json

{"data": [{"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card",
"status": {"value": "enabled",
"reason": "The SIM card is active, ready to connect to networks and consume data."
},
"type": "physical",
"iccid": "89310410106543789301",
"imsi": "081932214823362973",
"msisdn": "+13109976224",
"sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"tags": ["personal",
"customers",
"active-customers"
],
"data_limit": {"amount": "2048.0",
"unit": "MB"
},
"current_billing_period_consumed_data": {"amount": "2049.0",
"unit": "MB"
},
"actions_in_progress": true,
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
],
"meta": {"total_pages": 3,
"total_results": 55,
"page_number": 2,
"page_size": 25
}
}

Get SIM card

Returns the details regarding a specific SIM card.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

query Parameters

include_sim_card_group

boolean

Default: false

It includes the associated SIM card group object in the response when present.

Example: include_sim_card_group=true

Responses

200

Successful response

Response Schema: application/json

object (SIMCard)

id	string <uuid> Identifies the resource.
record_type	string
	object (SIMCardStatus)
type	string The type of SIM card Enum: "physical" "esim"
iccid	string 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.
imsi	string 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).
msisdn	string 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.
sim_card_group_id	string <uuid> The group SIMCardGroup identification. This attribute can be `null` when it's present in an associated resource.
tags	Array of strings Searchable tags associated with the SIM card
authorized_imeis	Array of strings <int64> List of IMEIs authorized to use a given SIM card.
current_imei	string <int64> IMEI of the device where a given SIM card is currently being used.
	object The SIM card individual data limit configuration.
	object The SIM card consumption so far in the current billing cycle.
actions_in_progress	boolean Default: false Indicate whether the SIM card has any pending (in-progress) actions.
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.
ipv4	string The SIM's address in the currently connected network. This IPv4 address is usually obtained dynamically, so it may vary according to the location or new connections.
ipv6	string The SIM's address in the currently connected network. This IPv6 address is usually obtained dynamically, so it may vary according to the location or new connections.
	object Current physical location data of a given SIM card. Accuracy is given in meters.
current_mnc	string Mobile Network Code of the current network to which the SIM card is connected. It's a two to three decimal digits that identify a network. This code is commonly seen joined with a Mobile Country Code (MCC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
current_mcc	string Mobile Country Code of the current network to which the SIM card is connected. It's a three decimal digit that identifies a country. This code is commonly seen joined with a Mobile Network Code (MNC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
live_data_session	string Indicates whether the device is actively connected to a network and able to run data. Enum: "connected" "disconnected" "unknown"

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards/{id}

Request samples

Response samples

200
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card",
"status": {"value": "enabled",
"reason": "The SIM card is active, ready to connect to networks and consume data."
},
"type": "physical",
"iccid": "89310410106543789301",
"imsi": "081932214823362973",
"msisdn": "+13109976224",
"sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"tags": ["personal",
"customers",
"active-customers"
],
"authorized_imeis": ["106516771852751",
"534051870479563",
"508821468377961"
],
"current_imei": "457032284023794",
"data_limit": {"amount": "2048.1",
"unit": "MB"
},
"current_billing_period_consumed_data": {"amount": "2049.0",
"unit": "MB"
},
"actions_in_progress": true,
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z",
"ipv4": "192.168.0.0",
"ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
"current_device_location": {"latitude": "41.143",
"longitude": "-8.605",
"accuracy": 1250,
"accuracy_unit": "m"
},
"current_mnc": "260",
"current_mcc": "410",
"live_data_session": "connected"
}
}

Update a SIM card

Updates SIM card data

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Request Body schema: application/json
required

	object (SIMCardStatus)
sim_card_group_id	string <uuid> The group SIMCardGroup identification. This attribute can be `null` when it's present in an associated resource.
tags	Array of strings Searchable tags associated with the SIM card
authorized_imeis	Array of strings <int64> List of IMEIs authorized to use a given SIM card.
	object The SIM card individual data limit configuration.

Responses

200

Successful response

Response Schema: application/json

object (SIMCard)

id	string <uuid> Identifies the resource.
record_type	string
	object (SIMCardStatus)
type	string The type of SIM card Enum: "physical" "esim"
iccid	string 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.
imsi	string 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).
msisdn	string 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.
sim_card_group_id	string <uuid> The group SIMCardGroup identification. This attribute can be `null` when it's present in an associated resource.
tags	Array of strings Searchable tags associated with the SIM card
authorized_imeis	Array of strings <int64> List of IMEIs authorized to use a given SIM card.
current_imei	string <int64> IMEI of the device where a given SIM card is currently being used.
	object The SIM card individual data limit configuration.
	object The SIM card consumption so far in the current billing cycle.
actions_in_progress	boolean Default: false Indicate whether the SIM card has any pending (in-progress) actions.
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.
ipv4	string The SIM's address in the currently connected network. This IPv4 address is usually obtained dynamically, so it may vary according to the location or new connections.
ipv6	string The SIM's address in the currently connected network. This IPv6 address is usually obtained dynamically, so it may vary according to the location or new connections.
	object Current physical location data of a given SIM card. Accuracy is given in meters.
current_mnc	string Mobile Network Code of the current network to which the SIM card is connected. It's a two to three decimal digits that identify a network. This code is commonly seen joined with a Mobile Country Code (MCC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
current_mcc	string Mobile Country Code of the current network to which the SIM card is connected. It's a three decimal digit that identifies a country. This code is commonly seen joined with a Mobile Network Code (MNC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
live_data_session	string Indicates whether the device is actively connected to a network and able to run data. Enum: "connected" "disconnected" "unknown"

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

patch/sim_cards/{id}

Request samples

application/json

{"status": { },
"sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"tags": ["personal",
"customers",
"active-customers"
],
"authorized_imeis": ["106516771852751",
"534051870479563",
"508821468377961"
],
"data_limit": {"amount": "2048.1",
"unit": "MB"
}
}

Response samples

200
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card",
"status": {"value": "enabled",
"reason": "The SIM card is active, ready to connect to networks and consume data."
},
"type": "physical",
"iccid": "89310410106543789301",
"imsi": "081932214823362973",
"msisdn": "+13109976224",
"sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"tags": ["personal",
"customers",
"active-customers"
],
"authorized_imeis": ["106516771852751",
"534051870479563",
"508821468377961"
],
"current_imei": "457032284023794",
"data_limit": {"amount": "2048.1",
"unit": "MB"
},
"current_billing_period_consumed_data": {"amount": "2049.0",
"unit": "MB"
},
"actions_in_progress": true,
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z",
"ipv4": "192.168.0.0",
"ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
"current_device_location": {"latitude": "41.143",
"longitude": "-8.605",
"accuracy": 1250,
"accuracy_unit": "m"
},
"current_mnc": "260",
"current_mcc": "410",
"live_data_session": "connected"
}
}

Deletes a SIM card

The SIM card will be decommissioned, removed from your account and you will stop being charged.
The SIM card won't be able to connect to the network after the deletion is completed, thus making it impossible to consume data.
Transitioning to the disabled state may take a period of time.
Until the transition is completed, the SIM card status will be disabling disabling.
In order to re-enable the SIM card, you will need to re-register it.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

200

Successful response

Response Schema: application/json

object (SIMCard)

id	string <uuid> Identifies the resource.
record_type	string
	object (SIMCardStatus)
type	string The type of SIM card Enum: "physical" "esim"
iccid	string 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.
imsi	string 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).
msisdn	string 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.
sim_card_group_id	string <uuid> The group SIMCardGroup identification. This attribute can be `null` when it's present in an associated resource.
tags	Array of strings Searchable tags associated with the SIM card
authorized_imeis	Array of strings <int64> List of IMEIs authorized to use a given SIM card.
current_imei	string <int64> IMEI of the device where a given SIM card is currently being used.
	object The SIM card individual data limit configuration.
	object The SIM card consumption so far in the current billing cycle.
actions_in_progress	boolean Default: false Indicate whether the SIM card has any pending (in-progress) actions.
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.
ipv4	string The SIM's address in the currently connected network. This IPv4 address is usually obtained dynamically, so it may vary according to the location or new connections.
ipv6	string The SIM's address in the currently connected network. This IPv6 address is usually obtained dynamically, so it may vary according to the location or new connections.
	object Current physical location data of a given SIM card. Accuracy is given in meters.
current_mnc	string Mobile Network Code of the current network to which the SIM card is connected. It's a two to three decimal digits that identify a network. This code is commonly seen joined with a Mobile Country Code (MCC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
current_mcc	string Mobile Country Code of the current network to which the SIM card is connected. It's a three decimal digit that identifies a country. This code is commonly seen joined with a Mobile Network Code (MNC) in a tuple that allows identifying a carrier known as PLMN (Public Land Mobile Network) code.
live_data_session	string Indicates whether the device is actively connected to a network and able to run data. Enum: "connected" "disconnected" "unknown"

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

delete/sim_cards/{id}

Request samples

Response samples

200
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card",
"status": {"value": "enabled",
"reason": "The SIM card is active, ready to connect to networks and consume data."
},
"type": "physical",
"iccid": "89310410106543789301",
"imsi": "081932214823362973",
"msisdn": "+13109976224",
"sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"tags": ["personal",
"customers",
"active-customers"
],
"authorized_imeis": ["106516771852751",
"534051870479563",
"508821468377961"
],
"current_imei": "457032284023794",
"data_limit": {"amount": "2048.1",
"unit": "MB"
},
"current_billing_period_consumed_data": {"amount": "2049.0",
"unit": "MB"
},
"actions_in_progress": true,
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z",
"ipv4": "192.168.0.0",
"ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
"current_device_location": {"latitude": "41.143",
"longitude": "-8.605",
"accuracy": 1250,
"accuracy_unit": "m"
},
"current_mnc": "260",
"current_mcc": "410",
"live_data_session": "connected"
}
}

Request a SIM card enable

This API enables a SIM card, connecting it to the network and making it possible to consume data.
To enable a SIM card, it must be associated with a SIM card group.
The API will trigger an asynchronous operation called a SIM Card Action. Transitioning to the enabled state may take a period of time. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

422

Unprocessable entity. Check the 'detail' field in response for details.

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/enable

Request samples

Response samples

202
422
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Request a SIM card disable

This API disables a SIM card, disconnecting it from the network and making it impossible to consume data.
The API will trigger an asynchronous operation called a SIM Card Action. Transitioning to the disabled state may take a period of time. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/disable

Request samples

Response samples

202
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Request setting a SIM card to standby

The SIM card will be able to connect to the network once the process to set it to standby has been completed, thus making it possible to consume data.
To set a SIM card to standby, it must be associated with SIM card group.
The API will trigger an asynchronous operation called a SIM Card Action. Transitioning to the standby state may take a period of time. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/set_standby

Request samples

Response samples

202
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Validate SIM cards registration codes

It validates whether SIM card registration codes are valid or not.

SecuritybearerAuth

Request

Request Body schema: application/json
required

registration_codes

Array of strings

Responses

200

Successful

Response Schema: application/json

Array of objects (SIMCardRegistrationCodeValidation)

Array

record_type	string
registration_code	string The 10-digit SIM card registration code
valid	boolean The attribute that denotes whether the code is valid or not
invalid_detail	string or null The validation message

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/actions/validate_registration_codes

Request samples

application/json

{"registration_codes": ["123456780",
"1231231230"
]
}

Response samples

200
default

application/json

{"data": [{"record_type": "sim_card_registration_code_validation",
"registration_code": "0123456789",
"valid": false,
"invalid_detail": "This code has already been used."
}
]
}

Create or update network preferences for a SIM card

This API sets network preferences for a SIM card.
Every SIM card has default network preferences defined on Telnyx. These preferences will determine how a SIMCard will connect to the network by considering a list of preferable operators.

The SIM card needs to be attached to the network so this can connect and SMS must be available, otherwise, the operation will fail. This preference will only be respected if the network is available, otherwise the strongest signal will be used.

The API will trigger an asynchronous operation called a SIM Card Action. Creating network preferences may take a period of time. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

422

Unprocessable entity. Check the 'detail' field in response for details.

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/set_network_preferences

Request samples

Response samples

202
422
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Delete network preferences for a SIM card

This API deletes network preferences for a SIM card.
The API will trigger an asynchronous operation called a SIM Card Action. Creating network preferences may take a period of time. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

422

Unprocessable entity. Check the 'detail' field in response for details.

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/delete_network_preferences

Request samples

Response samples

202
422
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Set network preferences

This API allows setting or updating a SIM card network preference.

Every SIM card has default network preferences defined on Telnyx. These preferences will determine how a SIMCard will connect to the network by considering a list of preferable operators.

There can be multiple scenarios where an operator can be preferred over another, for example, when a specific mobile operator can provide better network latency or better pricing.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Request Body schema: application/json

Array of objects (MobileNetworkOperatorPreferencesRequest)

A list of mobile network operators and the priority that should be applied when the SIM is connecting to the network.

Array

mobile_network_operator_id	string <uuid> The mobile network operator resource identification UUID.
priority	integer It determines what is the priority of a specific network operator that should be assumed by a SIM card when connecting to a network. The highest priority is 0, the second highest is 1 and so on.

Responses

202

A successful network preferences definition response.

The sent mobile_network_operators_preferences parameter won't be applied to the main resource right away - this is an asynchronous operation. While interacting with this API, you will face the following scenarios:

The first request for this API will return an empty mobile_network_operators_preferences with an in-progress OTA update resource in the ota_updates node containing the exact sent parameters to indicate the operation progress. The value will be applied to the principal object when the OTA update finishes its processing, thus indicating the SIM card network preference current state.
The subsequent requests will contain the current state, that is what's applied to the SIM card settings, and return the related OTA update in the ota_updates node.

The returned OTA updated (present in the ota_updates node) will, by default, be the resource related to the operation, not all of them.

Response Schema: application/json

object (SIMCardNetworkPreferenceWithOTAUpdates)

record_type	string
sim_card_id	string <uuid>
	Array of objects (MobileNetworkOperatorsPreferencesResponse) A list of mobile network operators and the priority that should be applied when the SIM is connecting to the network.
	Array of objects (OTAUpdate)
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

put/sim_cards/{sim_card_id}/network_preferences

Request samples

application/json

{"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"priority": 0
}
]
}

Response samples

202
default

application/json

{"data": {"record_type": "sim_card_network_preferences",
"sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
],
"ota_updates": [{"created_at": "2018-02-02T22:25:27.521Z",
"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "ota_update",
"settings": {"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
]
},
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"status": "in-progress",
"type": "sim_card_network_preferences",
"updated_at": "2018-02-02T22:25:27.521Z"
}
],
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Get network preferences

It returns the network preferences currently applied in the SIM card.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

query Parameters

include_ota_updates

boolean

Default: false

It includes the associated OTA update objects in the response when present.

Example: include_ota_updates=true

Responses

200

A successful network preferences definition response.

Response Schema: application/json

object (SIMCardNetworkPreferenceWithOTAUpdates)

record_type	string
sim_card_id	string <uuid>
	Array of objects (MobileNetworkOperatorsPreferencesResponse) A list of mobile network operators and the priority that should be applied when the SIM is connecting to the network.
	Array of objects (OTAUpdate)
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards/{sim_card_id}/network_preferences

Request samples

Response samples

200
default

application/json

{"data": {"record_type": "sim_card_network_preferences",
"sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
],
"ota_updates": [{"created_at": "2018-02-02T22:25:27.521Z",
"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "ota_update",
"settings": {"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
]
},
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"status": "in-progress",
"type": "sim_card_network_preferences",
"updated_at": "2018-02-02T22:25:27.521Z"
}
],
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

DELETE network preferences

This API asynchronously removes the custom-defined network preferences settings. After this operation is done the Telnyx default settings, the same applied for an unaltered SIM card, will be in place.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

A successful network preferences deletion response.

The delete won't be done right away - this is an asynchronous operation. The request will return the resource with an in-progress OTA update resource (in the ota_updates node) representing the delete operation. Similarly to the PUT API, the resource will only be deleted when the OTA updated is successfully completed.

Response Schema: application/json

object (SIMCardNetworkPreferenceWithOTAUpdates)

record_type	string
sim_card_id	string <uuid>
	Array of objects (MobileNetworkOperatorsPreferencesResponse) A list of mobile network operators and the priority that should be applied when the SIM is connecting to the network.
	Array of objects (OTAUpdate)
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

delete/sim_cards/{sim_card_id}/network_preferences

Request samples

Response samples

202
default

application/json

{"data": {"record_type": "sim_card_network_preferences",
"sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
],
"ota_updates": [{"created_at": "2018-02-02T22:25:27.521Z",
"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "ota_update",
"settings": {"mobile_network_operators_preferences": [{"mobile_network_operator_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"mobile_network_operator_name": "AT&T Mobility (USACG)",
"priority": 0
}
]
},
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"status": "in-progress",
"type": "sim_card_network_preferences",
"updated_at": "2018-02-02T22:25:27.521Z"
}
],
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Get SIM card public IP definition

It returns the public IP requested for a SIM card.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

200

Successful response

Response Schema: application/json

object (SIMCardPublicIP)

record_type	string
sim_card_id	string <uuid>
type	string Default: "ipv4" Value: "ipv4"
ip	string Default: null The provisioned IP address. This attribute will only be available when underlying resource status is in a "provisioned" status.
created_at	string ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards/{sim_card_id}/public_ip

Request samples

Response samples

200
default

application/json

{"data": {"record_type": "sim_card_public_ip",
"sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
"type": "ipv4",
"ip": "192.168.0.0",
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Request setting a SIM card public IP

This API makes a SIM card reachable on the public internet by mapping a random public IP to the SIM card.

The API will trigger an asynchronous operation called a SIM Card Action. The status of the SIM Card Action can be followed through the List SIM Card Action API.

Setting a Public IP to a SIM Card incurs a charge and will only succeed if the account has sufficient funds.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/set_public_ip

Request samples

Response samples

202
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Request removing a SIM card public IP

This API removes an existing public IP from a SIM card.

The API will trigger an asynchronous operation called a SIM Card Action. The status of the SIM Card Action can be followed through the List SIM Card Action API.

SecuritybearerAuth

Request

path Parameters

required

string <uuid>

Identifies the resource.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

202

Successful Response

Response Schema: application/json

object (SIMCardAction)

This object represents a SIM card action. It allows tracking the current status of an operation that impacts the SIM card.

id	string <uuid> (Id) Identifies the resource.
record_type	string
sim_card_id	string <uuid> The related SIM card identifier.
action_type	string The operation type. It can be one of the following: `enable` - move the SIM card to the `enabled` status `enable_standby_sim_card` - move a SIM card previously on the `standby` status to the `enabled` status after it consumes data. `disable` - move the SIM card to the `disabled` status `set_standby` - move the SIM card to the `standby` status Enum: "enable" "enable_standby_sim_card" "disable" "set_standby"
	object
settings	object or null A JSON object representation of the action params.
created_at	string (CreatedAt) ISO 8601 formatted date-time indicating when the resource was created.
updated_at	string (UpdatedAt) ISO 8601 formatted date-time indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

post/sim_cards/{id}/actions/remove_public_ip

Request samples

Response samples

202
default

application/json

{"data": {"id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"record_type": "sim_card_action",
"sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
"action_type": "enable",
"status": {"value": "completed",
"reason": "The data limit was exceeded."
},
"settings": { },
"created_at": "2018-02-02T22:25:27.521Z",
"updated_at": "2018-02-02T22:25:27.521Z"
}
}

Get SIM card device details

It returns the device details where a SIM card is currently being used.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

200

Successful response

Response Schema: application/json

object (SIMCardDeviceDetails)

record_type	string
imei	string <int64> IMEI of the device where the SIM card is being used in.
model_name	string Brand of the device where the SIM card is being used in.
brand_name	string Brand of the device where the SIM card is being used in.
device_type	string Type of the device where the SIM card is being used in.
operating_system	string Operating system of the device where the SIM card is being used in.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards/{sim_card_id}/device_details

Request samples

Response samples

200
default

application/json

{"data": {"record_type": "device_details",
"imei": "457032284023794",
"model_name": "iPad Pro 11 2020 Cellular",
"brand_name": "Apple",
"device_type": "Tablet",
"operating_system": "iOS 12"
}
}

Get activation QR code for an eSIM

It returns the contents for the activation QR code for an eSIM.

This API is only available for eSIMs. If the given SIM is a physical SIM card, or has already been installed, an error will be returned.

SecuritybearerAuth

Request

path Parameters

sim_card_id

required

string <uuid>

Identifies a SIM card.

Example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58

Responses

200

Successful response

Response Schema: application/json

object (SIMCardActivationCode)

record_type	string
activation_code	string Contents of the eSIM activation QR code.

default

Unexpected error

Response Schema: application/json

Array of objects (Error)

Array

code required	string <int>
title required	string
detail	string
	object
meta	object

get/sim_cards/{sim_card_id}/activation_code

Request samples

Response samples

200
default

application/json

{"data": {"record_type": "sim_card_activation_code",
"activation_code": "LPA:1$...."
}
}

Register SIM cards

Register the SIM cards associated with the provided registration codes to the current user's account.

If sim_card_group_id is provided, the SIM cards will be associated with that group. Otherwise, the default group for the current user will be used.

SecuritybearerAuth

Request

Request Body schema: application/json
required

sim_card_group_id	string <uuid> The group SIMCardGroup identification. This attribute can be `null` when it's present in an associated resource.
tags	Array of strings Searchable tags associated with the SIM card
registration_codes required	Array of strings
status	string Default: "enabled" Status on which the SIM card will be set after being successful registered. Enum: "enabled" "disabled" "standby"

Responses

202

Successful response

Response Schema: application/json

Array of objects (SIMCard)

SIM Cards

Get all SIM cards

query Parameters

Response Schema: application/json

Response Schema: application/json

Get SIM card

path Parameters

query Parameters

Response Schema: application/json

Response Schema: application/json

Update a SIM card

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Response Schema: application/json

Deletes a SIM card

path Parameters

Response Schema: application/json

Response Schema: application/json

Request a SIM card enable

path Parameters

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Request a SIM card disable

path Parameters

Response Schema: application/json

Response Schema: application/json

Request setting a SIM card to standby

path Parameters

Response Schema: application/json

Response Schema: application/json

Validate SIM cards registration codes

Request Body schema: application/jsonrequired

Response Schema: application/json

Response Schema: application/json

Create or update network preferences for a SIM card

path Parameters

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Delete network preferences for a SIM card

path Parameters

Response Schema: application/json

Response Schema: application/json

Response Schema: application/json

Set network preferences

path Parameters

Request Body schema: application/json

Response Schema: application/json

Response Schema: application/json

Get network preferences

path Parameters

query Parameters

Response Schema: application/json

Response Schema: application/json

DELETE network preferences

path Parameters

Response Schema: application/json

Response Schema: application/json

Get SIM card public IP definition

path Parameters

Response Schema: application/json

Response Schema: application/json

Request setting a SIM card public IP

path Parameters

Response Schema: application/json

Response Schema: application/json

Request removing a SIM card public IP

path Parameters

Response Schema: application/json

Response Schema: application/json

Get SIM card device details

path Parameters

Response Schema: application/json

Response Schema: application/json

Get activation QR code for an eSIM

path Parameters

Response Schema: application/json

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required