SIM Cards API

SIM Cards operations API

Bulk Network Preferences for SIM cards

This API allows dispatching the same operation described for the PUT sim_cards/:sim_card_id/network_preferences API for multiple SIM cards at once.

Although, a SIM card network preference may fail individually under any validation triggered as a consequence of its state. For example, a SIM can't have an in-progress OTA update for applying a Network Preference, so they'll fail when requested in this API. In that scenario, the specific error will be present in the response along with the successful definitions in the "errors" response node.

SecuritybearerAuth
Request
Request Body schema: application/json
Array of objects (MobileOperatorNetworksPreferencesRequest)

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

sim_card_ids
Array of strings <uuid>
Responses
202
Response Schema: application/json
Array of objects (SIMCardNetworkPreferenceWithOTAUpdates)

Multi requested SIM cards network preferences.

Array of objects (Error)
422

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

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
put/actions/network_preferences/sim_cards
Request samples
application/json
{
  • "mobile_operator_networks_preferences": [
    • {
      • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "priority": 0
      }
    ],
  • "sim_card_ids": [
    • "6b14e151-8493-4fa1-8664-1cc4e6d14158",
    • "6b14e151-8493-4fa1-8664-1cc4e6d14158"
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "mobile_operator_networks_preferences": [
        • {
          • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
          • "mobile_operator_network_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_operator_networks_preferences": [
              • {
                • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
                • "mobile_operator_network_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"
          }
        ],
      • "record_type": "sim_card_network_preferences",
      • "sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "errors": [
    • {
      • "code": "string",
      • "detail": "string",
      • "meta": { },
      • "source": {
        • "parameter": "string",
        • "pointer": "/json/pointer"
        },
      • "title": "string"
      }
    ]
}

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
registration_codes
required
Array of strings
sim_card_group_id
string <uuid>

The group SIMCardGroup identification. This attribute can be null when it's present in an associated resource.

status
string
Default: "enabled"

Status on which the SIM card will be set after being successful registered.

Enum: "enabled" "disabled" "standby"
tags
Array of strings

Searchable tags associated with the SIM card

Responses
202

Successful response

Response Schema: application/json
Array of objects (SIMCard)

Successfully registered SIM cards.

Array of objects (Error)
post/actions/register/sim_cards
Request samples
application/json
{
  • "registration_codes": [
    • "0000000001",
    • "0000000002",
    • "0000000003"
    ],
  • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
  • "status": "standby",
  • "tags": [
    • "personal",
    • "customers",
    • "active-customers"
    ]
}
Response samples
application/json
{
  • "data": [
    • {
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "current_billing_period_consumed_data": {
        • "amount": "2049.0",
        • "unit": "MB"
        },
      • "data_limit": {
        • "amount": "2048.0",
        • "unit": "MB"
        },
      • "iccid": "89310410106543789301",
      • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "imsi": 81932214823362980,
      • "msisdn": "+13109976224",
      • "record_type": "sim_card",
      • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "status": {
        • "reason": "The SIM card is active, ready to connect to networks and consume data.",
        • "value": "enabled"
        },
      • "tags": [
        • "personal",
        • "customers",
        • "active-customers"
        ],
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "errors": [
    • {
      • "code": "string",
      • "detail": "string",
      • "meta": { },
      • "source": {
        • "parameter": "string",
        • "pointer": "/json/pointer"
        },
      • "title": "string"
      }
    ]
}

List SIM card data usage notifications

Lists a paginated collection of SIM card data usage notifications. It enables exploring the collection using specific 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

filter[sim_card_id]
string <uuid>

A valid SIM card ID.

Example: filter[sim_card_id]=47a1c2b0-cc7b-4ab1-bb98-b33fb0fc61b9
Responses
200

Successful response

Response Schema: application/json
Array of objects (SimCardDataUsageNotification)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/sim_card_data_usage_notifications
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
      • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
      • "threshold": {
        • "amount": "2048.0",
        • "unit": "MB"
        },
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "meta": {
    • "page_number": 2,
    • "page_size": 25,
    • "total_pages": 3,
    • "total_results": 55
    }
}
Create a new SIM card data usage notification
Creates a new SIM card data usage notification.


SecuritybearerAuth 
Request 
Request Body schema: application/json
required
sim_card_id
required
string <uuid> 
The identification UUID of the related SIM card resource.


 
required
object
Data usage threshold that will trigger the notification.


 
Responses 
201
Successful response


Response Schema: application/json
object (SimCardDataUsageNotification) 
The SIM card individual data usage notification information.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
id
string <uuid> 
Identifies the resource.


 
record_type
string
 
sim_card_id
string <uuid> 
The identification UUID of the related SIM card resource.


 
object
Data usage threshold that will trigger the notification.


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_card_data_usage_notifications
Request samples 
application/json
{
  • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
  • "threshold": {
    • "amount": "2048.1",
    • "unit": "MB"
    }
}
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
    • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
    • "threshold": {
      • "amount": "2048.0",
      • "unit": "MB"
      },
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Delete SIM card data usage notifications
Delete the SIM Card Data Usage Notification.


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Identifies the resource.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
Responses 
200
Successful response


Response Schema: application/json
object (SimCardDataUsageNotification) 
The SIM card individual data usage notification information.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
id
string <uuid> 
Identifies the resource.


 
record_type
string
 
sim_card_id
string <uuid> 
The identification UUID of the related SIM card resource.


 
object
Data usage threshold that will trigger the notification.


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
delete/sim_card_data_usage_notifications/{id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
    • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
    • "threshold": {
      • "amount": "2048.0",
      • "unit": "MB"
      },
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Get a single SIM card data usage notification
Get a single SIM Card Data Usage Notification.


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Identifies the resource.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
Responses 
200
Successful response


Response Schema: application/json
object (SimCardDataUsageNotification) 
The SIM card individual data usage notification information.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
id
string <uuid> 
Identifies the resource.


 
record_type
string
 
sim_card_id
string <uuid> 
The identification UUID of the related SIM card resource.


 
object
Data usage threshold that will trigger the notification.


 
updated_at
string
ISO 8601 formatted date-time indicating when the resource was updated.


 
404
Resource not found


Response Schema: application/json
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_card_data_usage_notifications/{id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
    • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
    • "threshold": {
      • "amount": "2048.0",
      • "unit": "MB"
      },
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Updates information for a SIM Card Data Usage Notification
Updates information for a SIM Card Data Usage Notification.


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Identifies the resource.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
Request Body schema: application/json
required
sim_card_id
string <uuid> 
The identification UUID of the related SIM card resource.


 
object
Data usage threshold that will trigger the notification.


 
Responses 
200
Successful response


Response Schema: application/json
object (SimCardDataUsageNotification) 
The SIM card individual data usage notification information.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
id
string <uuid> 
Identifies the resource.


 
record_type
string
 
sim_card_id
string <uuid> 
The identification UUID of the related SIM card resource.


 
object
Data usage threshold that will trigger the notification.


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
patch/sim_card_data_usage_notifications/{id}
Request samples 
application/json
{
  • "created_at": "2018-02-02T22:25:27.521Z",
  • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
  • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
  • "threshold": {
    • "amount": "2048.0",
    • "unit": "MB"
    },
  • "updated_at": "2018-02-02T22:25:27.521Z"
}
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "id": "79228acc-3f08-4e70-ac68-cb5aae8b537a",
    • "sim_card_id": "b34c1683-cd85-4493-b9a5-315eb4bc5e19",
    • "threshold": {
      • "amount": "2048.0",
      • "unit": "MB"
      },
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
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"  
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.SIMCard.list(page={"number":1,"size":20})
Response samples 
application/json
{
  • "data": [
    • {
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "current_billing_period_consumed_data": {
        • "amount": "2049.0",
        • "unit": "MB"
        },
      • "data_limit": {
        • "amount": "2048.0",
        • "unit": "MB"
        },
      • "iccid": "89310410106543789301",
      • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "imsi": 81932214823362980,
      • "msisdn": "+13109976224",
      • "record_type": "sim_card",
      • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "status": {
        • "reason": "The SIM card is active, ready to connect to networks and consume data.",
        • "value": "enabled"
        },
      • "tags": [
        • "personal",
        • "customers",
        • "active-customers"
        ],
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "meta": {
    • "page_number": 2,
    • "page_size": 25,
    • "total_pages": 3,
    • "total_results": 55
    }
}
Request bulk setting SIM card public IPs.
This API triggers an asynchronous operation to set a public IP for each of the specified SIM cards.

For each SIM Card a SIM Card Action will be generated. The status of the SIM Card Action can be followed through the List SIM Card Action API.


SecuritybearerAuth 
Request 
Request Body schema: application/json
sim_card_ids
required
Array of strings <uuid>  (Id) 
 
Responses 
202
Successful Response


Response Schema: application/json
object (BulkSIMCardAction) 
This object represents a bulk SIM card action. It groups SIM card actions created through a bulk endpoint under a single resource for further lookup.


 
action_type
string
The operation type. It can be one of the following: 


    

  • bulk_set_public_ips - set a public IP for each specified SIM card
    • 

 Value: "bulk_set_public_ips"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the bulk action payload.


 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date 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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/actions/bulk_set_public_ips
Request samples 
application/json
{
  • "sim_card_ids": [
    • "6b14e151-8493-4fa1-8664-1cc4e6d14158"
    ]
}
Response samples 
application/json
{
  • "data": {
    • "action_type": "bulk_set_public_ips",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "bulk_sim_card_action",
    • "settings": { },
    • "updated_at": "2020-02-03T22: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 
invalid_detail
string
The validation message


 
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


 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/actions/validate_registration_codes
Request samples 
application/json
{
  • "registration_codes": [
    • "123456780",
    • "1231231230"
    ]
}
Response samples 
application/json
{
  • "data": [
    • {
      • "invalid_detail": "This code has already been used.",
      • "record_type": "sim_card_registration_code_validation",
      • "registration_code": 123456789,
      • "valid": false
      }
    ]
}
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
id
required
string <uuid> 
Identifies the resource.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
Responses 
200
Successful response


Response Schema: application/json
object (SIMCard) 
 
authorized_imeis
Array of strings <int64> 
List of IMEIs authorized to use a given SIM card.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
object
The SIM card consumption so far in the current billing cycle.


 
object
Current physical location data of a given SIM card. Accuracy is given in meters.


 
current_imei
string <int64> 
IMEI of the device where a given SIM card is currently being used.


 
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.


 
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.


 
object
The SIM card individual data limit configuration.


 
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.


 
id
string <uuid> 
Identifies the resource.


 
imsi
string
SIM cards are identified on their individual operator networks 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).


 
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.


 
live_data_session
string
Indicates whether the device is actively connected to a network and able to run data.


 Enum: "connected" "disconnected" "unknown"  
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.


 
record_type
string
 
sim_card_group_id
string <uuid> 
The group SIMCardGroup identification. This attribute can be null when it's present in an associated resource.


 
object (SIMCardStatus) 
 
tags
Array of strings
Searchable tags associated with the SIM card


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
delete/sim_cards/{id}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

res = telnyx.SIMCard.retrieve("id")
res.delete()
Response samples 
application/json
{
  • "data": {
    • "authorized_imeis": [
      • "106516771852751",
      • "534051870479563",
      • "508821468377961"
      ],
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "current_billing_period_consumed_data": {
      • "amount": "2049.0",
      • "unit": "MB"
      },
    • "current_device_location": {
      • "accuracy": 1250,
      • "accuracy_unit": "m",
      • "latitude": "41.143",
      • "longitude": "-8.605"
      },
    • "current_imei": "457032284023794",
    • "current_mcc": "410",
    • "current_mnc": "260",
    • "data_limit": {
      • "amount": "2048.1",
      • "unit": "MB"
      },
    • "iccid": "89310410106543789301",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "imsi": 81932214823362980,
    • "ipv4": "192.168.0.0",
    • "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    • "live_data_session": "connected",
    • "msisdn": "+13109976224",
    • "record_type": "sim_card",
    • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The SIM card is active, ready to connect to networks and consume data.",
      • "value": "enabled"
      },
    • "tags": [
      • "personal",
      • "customers",
      • "active-customers"
      ],
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Get SIM card
Returns the details regarding a specific SIM card.


SecuritybearerAuth 
Request 
path Parameters
id
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) 
 
authorized_imeis
Array of strings <int64> 
List of IMEIs authorized to use a given SIM card.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
object
The SIM card consumption so far in the current billing cycle.


 
object
Current physical location data of a given SIM card. Accuracy is given in meters.


 
current_imei
string <int64> 
IMEI of the device where a given SIM card is currently being used.


 
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.


 
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.


 
object
The SIM card individual data limit configuration.


 
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.


 
id
string <uuid> 
Identifies the resource.


 
imsi
string
SIM cards are identified on their individual operator networks 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).


 
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.


 
live_data_session
string
Indicates whether the device is actively connected to a network and able to run data.


 Enum: "connected" "disconnected" "unknown"  
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.


 
record_type
string
 
sim_card_group_id
string <uuid> 
The group SIMCardGroup identification. This attribute can be null when it's present in an associated resource.


 
object (SIMCardStatus) 
 
tags
Array of strings
Searchable tags associated with the SIM card


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards/{id}
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.SIMCard.retrieve("id",include_sim_card_group=True)
Response samples 
application/json
{
  • "data": {
    • "authorized_imeis": [
      • "106516771852751",
      • "534051870479563",
      • "508821468377961"
      ],
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "current_billing_period_consumed_data": {
      • "amount": "2049.0",
      • "unit": "MB"
      },
    • "current_device_location": {
      • "accuracy": 1250,
      • "accuracy_unit": "m",
      • "latitude": "41.143",
      • "longitude": "-8.605"
      },
    • "current_imei": "457032284023794",
    • "current_mcc": "410",
    • "current_mnc": "260",
    • "data_limit": {
      • "amount": "2048.1",
      • "unit": "MB"
      },
    • "iccid": "89310410106543789301",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "imsi": 81932214823362980,
    • "ipv4": "192.168.0.0",
    • "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    • "live_data_session": "connected",
    • "msisdn": "+13109976224",
    • "record_type": "sim_card",
    • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The SIM card is active, ready to connect to networks and consume data.",
      • "value": "enabled"
      },
    • "tags": [
      • "personal",
      • "customers",
      • "active-customers"
      ],
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
Update a SIM card
Updates SIM card data


SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
Identifies the resource.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
Request Body schema: application/json
required
authorized_imeis
Array of strings <int64> 
List of IMEIs authorized to use a given SIM card.


 
object
The SIM card individual data limit configuration.


 
sim_card_group_id
string <uuid> 
The group SIMCardGroup identification. This attribute can be null when it's present in an associated resource.


 
object (SIMCardStatus) 
 
tags
Array of strings
Searchable tags associated with the SIM card


 
Responses 
200
Successful response


Response Schema: application/json
object (SIMCard) 
 
authorized_imeis
Array of strings <int64> 
List of IMEIs authorized to use a given SIM card.


 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
object
The SIM card consumption so far in the current billing cycle.


 
object
Current physical location data of a given SIM card. Accuracy is given in meters.


 
current_imei
string <int64> 
IMEI of the device where a given SIM card is currently being used.


 
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.


 
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.


 
object
The SIM card individual data limit configuration.


 
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.


 
id
string <uuid> 
Identifies the resource.


 
imsi
string
SIM cards are identified on their individual operator networks 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).


 
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.


 
live_data_session
string
Indicates whether the device is actively connected to a network and able to run data.


 Enum: "connected" "disconnected" "unknown"  
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.


 
record_type
string
 
sim_card_group_id
string <uuid> 
The group SIMCardGroup identification. This attribute can be null when it's present in an associated resource.


 
object (SIMCardStatus) 
 
tags
Array of strings
Searchable tags associated with the SIM card


 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
patch/sim_cards/{id}
Request samples 
application/json
{
  • "authorized_imeis": [
    • "106516771852751",
    • "534051870479563",
    • "508821468377961"
    ],
  • "data_limit": {
    • "amount": "2048.1",
    • "unit": "MB"
    },
  • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
  • "status": { },
  • "tags": [
    • "personal",
    • "customers",
    • "active-customers"
    ]
}
Response samples 
application/json
{
  • "data": {
    • "authorized_imeis": [
      • "106516771852751",
      • "534051870479563",
      • "508821468377961"
      ],
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "current_billing_period_consumed_data": {
      • "amount": "2049.0",
      • "unit": "MB"
      },
    • "current_device_location": {
      • "accuracy": 1250,
      • "accuracy_unit": "m",
      • "latitude": "41.143",
      • "longitude": "-8.605"
      },
    • "current_imei": "457032284023794",
    • "current_mcc": "410",
    • "current_mnc": "260",
    • "data_limit": {
      • "amount": "2048.1",
      • "unit": "MB"
      },
    • "iccid": "89310410106543789301",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "imsi": 81932214823362980,
    • "ipv4": "192.168.0.0",
    • "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    • "live_data_session": "connected",
    • "msisdn": "+13109976224",
    • "record_type": "sim_card",
    • "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The SIM card is active, ready to connect to networks and consume data.",
      • "value": "enabled"
      },
    • "tags": [
      • "personal",
      • "customers",
      • "active-customers"
      ],
    • "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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date 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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/delete_network_preferences
Request samples 
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22: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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date indicating when the resource was updated.


 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/disable
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: simCard } = await telnyx.simCards.retrieve('123');
await simCard.disable();
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22:25:27.521Z"
    }
}
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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date 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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/enable
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: simCard } = await telnyx.simCards.retrieve('123');
await simCard.enable();
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22: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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date indicating when the resource was updated.


 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/remove_public_ip
Request samples 
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22:25:27.521Z"
    }
}
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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date 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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/set_network_preferences
Request samples 
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22: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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date indicating when the resource was updated.


 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/set_public_ip
Request samples 
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22: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
id
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.


 
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"  
created_at
string (CreatedAt) 
ISO 8601 formatted date indicating when the resource was created.


 
id
string <uuid>  (Id) 
Identifies the resource.


 
record_type
string
 
settings
object
A JSON object representation of the action params.


 
sim_card_id
string <uuid> 
The related SIM card identifier.


 
object
 
updated_at
string (UpdatedAt) 
ISO 8601 formatted date indicating when the resource was updated.


 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
post/sim_cards/{id}/actions/set_standby
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: simCard } = await telnyx.simCards.retrieve('123');
await simCard.setStandby();
Response samples 
application/json
{
  • "data": {
    • "action_type": "enable",
    • "created_at": "2020-02-02T22:25:27.521Z",
    • "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "record_type": "sim_card_action",
    • "settings": { },
    • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    • "status": {
      • "reason": "The data limit was exceeded.",
      • "value": "completed"
      },
    • "updated_at": "2020-02-03T22: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) 
 
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.


 
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.


 
operating_system
string
Operating system of the device where the SIM card is being used in.


 
record_type
string
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards/{sim_card_id}/device_details
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data } = await telnyx.simCards.deviceDetails.retrieve('sim_card_id');
Response samples 
application/json
{
  • "data": {
    • "brand_name": "Apple",
    • "device_type": "Tablet",
    • "imei": "457032284023794",
    • "model_name": "iPad Pro 11 2020 Cellular",
    • "operating_system": "iOS 12",
    • "record_type": "device_details"
    }
}
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) 
 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
Array of objects (MobileOperatorNetworksPreferencesResponse) 
A list of mobile operator networks and the priority that should be applied when the SIM is connecting to the network.


 
Array of objects (OTAUpdate) 
 
record_type
string
 
sim_card_id
string <uuid> 
 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
delete/sim_cards/{sim_card_id}/network_preferences
Request samples 
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "mobile_operator_networks_preferences": [
      • {
        • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
        • "mobile_operator_network_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_operator_networks_preferences": [
            • {
              • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
              • "mobile_operator_network_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"
        }
      ],
    • "record_type": "sim_card_network_preferences",
    • "sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
    • "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) 
 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
Array of objects (MobileOperatorNetworksPreferencesResponse) 
A list of mobile operator networks and the priority that should be applied when the SIM is connecting to the network.


 
Array of objects (OTAUpdate) 
 
record_type
string
 
sim_card_id
string <uuid> 
 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards/{sim_card_id}/network_preferences
Request samples 
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "mobile_operator_networks_preferences": [
      • {
        • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
        • "mobile_operator_network_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_operator_networks_preferences": [
            • {
              • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
              • "mobile_operator_network_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"
        }
      ],
    • "record_type": "sim_card_network_preferences",
    • "sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
    • "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 (MobileOperatorNetworkPreferencesRequest) 
A list of mobile operator networks and the priority that should be applied when the SIM is connecting to the network.


 
 Array 
mobile_operator_network_id
string <uuid> 
The mobile operator network resource identification UUID.


 
priority
integer
It determines what is the priority of a specific operator network 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_operator_networks_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_operator_networks_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) 
 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
Array of objects (MobileOperatorNetworksPreferencesResponse) 
A list of mobile operator networks and the priority that should be applied when the SIM is connecting to the network.


 
Array of objects (OTAUpdate) 
 
record_type
string
 
sim_card_id
string <uuid> 
 
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
put/sim_cards/{sim_card_id}/network_preferences
Request samples 
application/json
{
  • "mobile_operator_networks_preferences": [
    • {
      • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "priority": 0
      }
    ]
}
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "mobile_operator_networks_preferences": [
      • {
        • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
        • "mobile_operator_network_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_operator_networks_preferences": [
            • {
              • "mobile_operator_network_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
              • "mobile_operator_network_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"
        }
      ],
    • "record_type": "sim_card_network_preferences",
    • "sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
    • "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) 
 
created_at
string
ISO 8601 formatted date-time indicating when the resource was created.


 
ip
string
 Default:  null
The provisioned IP address. This attribute will only be available when underlying resource status is in a "provisioned" status.


 
record_type
string
 
sim_card_id
string <uuid> 
 
type
string
 Default:  "ipv4"
 Value: "ipv4"  
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> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards/{sim_card_id}/public_ip
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const {data: simCard} = await telnyx.simCards.retrieve('123');
const {data: publicIPInfo} = await simCard.retrievePublicIP();
Response samples 
application/json
{
  • "data": {
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "ip": "192.168.0.0",
    • "record_type": "sim_card_public_ip",
    • "sim_card_id": "6b14e151-8493-4fa1-8664-1cc4e6d14158",
    • "type": "ipv4",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}
List wireless connectivity logs
This API allows listing a paginated collection of Wireless Connectivity Logs associated with a SIM Card, for troubleshooting purposes.


SecuritybearerAuth 
Request 
path Parameters
sim_card_id
required
string <uuid> 
Identifies a SIM card.


 
 Example:  6a09cdc3-8948-47f0-aa62-74ac943d6c58
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


 
Responses 
200
Successful response


Response Schema: application/json
Array of objects (WirelessConnectivityLog) 
 
object (PaginationMeta) 
 
default
Unexpected error


Response Schema: application/json
Array of objects (Error) 
 
 Array 
code
required
string <int> 
 
detail
string
 
meta
object
 
object
 
title
required
string
 
get/sim_cards/{sim_card_id}/wireless_connectivity_logs
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "apn": "data00.telnyx",
      • "cell_id": "311210-6813",
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "id": 137509451,
      • "imei": "490154203237518",
      • "imsi": 81932214823362980,
      • "ipv4": "192.168.0.0",
      • "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
      • "last_seen": "2018-02-02T22:25:27.521Z",
      • "log_type": "registration",
      • "mobile_country_code": "310",
      • "mobile_network_code": "410",
      • "radio_access_technology": "LTE",
      • "record_type": "wireless_connectivity_log",
      • "sim_card_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
      • "start_time": "2018-02-02T22:25:27.521Z",
      • "state": "provisioned",
      • "stop_time": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "meta": {
    • "page_number": 2,
    • "page_size": 25,
    • "total_pages": 3,
    • "total_results": 55
    }
}