This is the API V2 documentation. To switch out of beta revert back to our API V1.

Telnyx DevelopersAPI v2
Sign inTelnyx Developers
Open Menu
DocsAPI ReferenceJoin Slack Community
Create an AccountSign in
Questions on setup? Talk to our experts
Open SidemenuAPI Reference
API Reference
Close Sidemenu

SIM Cards

Get all SIM cardsSimCardsGet

get https://api.telnyx.com/v2/sim_cards

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

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/sim_cards?page[size]=10&filter[tags][]=region_5&filter[tags][]=ext_cards"
Parameters
In query
page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page

Default: 20
include_sim_card_group
boolean
optional

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

Default: false
Example: true
filter[sim_card_group_id]
string (uuid)
optional

A valid SIM card group ID.

Example: "47a1c2b0-cc7b-4ab1-bb98-b33fb0fc61b9"
filter[tags]
array of string
optional

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: [ "personal", "customers", "active-customers" ]
filter[iccid]
string
optional

A search string to partially match for the SIM card's ICCID.

Example: "89310410106543789301"
Responses
200

Successful response

default

Unexpected error

Success Response
{
  "data": [
    {
      "created_at": "2018-02-02T22:25:27.521Z",
      "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": "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
  }
}

Get SIM cardSimCardGet

get https://api.telnyx.com/v2/sim_cards/{id}

Returns the details regarding a specific SIM card.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58?include_sim_card_group=true"
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
In query
include_sim_card_group
boolean
optional

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

Default: false
Example: true
Responses
200

Successful response

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-02-02T22:25:27.521Z",
    "iccid": "89310410106543789301",
    "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "imsi": 81932214823362980,
    "ipv4": "192.168.0.0",
    "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    "msisdn": "+13109976224",
    "record_type": "sim_card",
    "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "status": "enabled",
    "tags": [
      "personal",
      "customers",
      "active-customers"
    ],
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Update a SIM cardSimCardUpdate

patch https://api.telnyx.com/v2/sim_cards/{id}

Updates a SIM card's group and tags

curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"tags": ["region_7", "int_cards"]}' \
  https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
In body
sim_card_group_id
string (uuid)
optional

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

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
tags
array of string
optional

Searchable tags associated with the SIM card

Example: [ "personal", "customers", "active-customers" ]
Responses
200

Successful response

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-02-02T22:25:27.521Z",
    "iccid": "89310410106543789301",
    "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "imsi": 81932214823362980,
    "ipv4": "192.168.0.0",
    "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    "msisdn": "+13109976224",
    "record_type": "sim_card",
    "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "status": "enabled",
    "tags": [
      "personal",
      "customers",
      "active-customers"
    ],
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Deletes a SIM cardSimCardDelete

delete https://api.telnyx.com/v2/sim_cards/{id}

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.

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58"
Parameters
In path
id
string (uuid)
required

Identifies the resource.

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

Successful response

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-02-02T22:25:27.521Z",
    "iccid": "89310410106543789301",
    "id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "imsi": 81932214823362980,
    "ipv4": "192.168.0.0",
    "ipv6": "2001:cdba:0000:0000:0000:0000:3257:9652",
    "msisdn": "+13109976224",
    "record_type": "sim_card",
    "sim_card_group_id": "6a09cdc3-8948-47f0-aa62-74ac943d6c58",
    "status": "enabled",
    "tags": [
      "personal",
      "customers",
      "active-customers"
    ],
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Request a SIM card enableSimCardEnable

post https://api.telnyx.com/v2/sim_cards/{id}/actions/enable

The SIM card will be able to connect to the network once the enabling is complete, thus making it possible to consume data.
To enable a SIM card, it must be associated with a data-enabled SIM card group.
Transitioning to the enabled state may take a period of time. Until the transition is completed, the SIM card status will be enabling.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{}' \
  https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58/actions/enable
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
Responses
202

Successful response

422

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

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-02-02T22:25:27.521Z",
    "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": "enabled",
    "tags": [
      "personal",
      "customers",
      "active-customers"
    ],
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Request a SIM card disableSimCardDisable

post https://api.telnyx.com/v2/sim_cards/{id}/actions/disable

The SIM card won't be able to connect to the network after the disabling 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.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{}' \
  https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58/actions/disable
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
Responses
202

Successful response

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2018-02-02T22:25:27.521Z",
    "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": "enabled",
    "tags": [
      "personal",
      "customers",
      "active-customers"
    ],
    "updated_at": "2018-02-02T22:25:27.521Z"
  }
}

Register SIM cardsSimCardRegister

post https://api.telnyx.com/v2/actions/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, which is already data-enabled, will be used.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"registration_codes": ["1234567890, 123456332601"]}' \
  https://api.telnyx.com/v2/actions/register/sim_cards
Parameters
In body
registration_codes
array of string
optional
Example: [ "0000000001", "0000000002", "0000000003" ]
sim_card_group_id
string (uuid)
optional

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

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
tags
array of string
optional

Searchable tags associated with the SIM card

Example: [ "personal", "customers", "active-customers" ]
Responses
202

Successful response

Success Response
{
  "data": [
    {
      "created_at": "2018-02-02T22:25:27.521Z",
      "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": "enabled",
      "tags": [
        "personal",
        "customers",
        "active-customers"
      ],
      "updated_at": "2018-02-02T22:25:27.521Z"
    }
  ]
}

Get network preferencesSIMCardNetworkPreferencesGet

get https://api.telnyx.com/v2/sim_cards/{id}/network_preferences

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

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58/network_preferences?include_ota_updates=true"
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
In query
include_ota_updates
boolean
optional

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

Default: false
Example: true
Responses
200

A successful network preferences definition response.

default

Unexpected error

Success Response
{
  "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 preferencesSIMCardNetworkPreferencesPut

put https://api.telnyx.com/v2/sim_cards/{id}/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.

curl -X PUT \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"mobile_operator_networks_preferences":"array"}' \
  https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58/network_preferences
Parameters
In path
id
string (uuid)
required

Identifies the resource.

Example: "6a09cdc3-8948-47f0-aa62-74ac943d6c58"
In body
mobile_operator_networks_preferences
array of object
optional

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

mobile_operator_network_id
string (uuid)

The mobile operator network resource identification UUID.

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

0
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.

default

Unexpected error

Success Response
{
  "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"
  }
}

DELETE network preferencesSIMCardNetworkPreferencesDelete

delete https://api.telnyx.com/v2/sim_cards/{id}/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.

curl -X DELETE \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/sim_cards/6a09cdc3-8948-47f0-aa62-74ac943d6c58/network_preferences"
Parameters
In path
id
string (uuid)
required

Identifies the resource.

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.

default

Unexpected error

Success Response
{
  "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"
  }
}

Bulk Network Preferences for SIM cardsBulkSIMCardNetworkPreferences

put https://api.telnyx.com/v2/actions/network_preferences/sim_cards

This API allows dispatching the same operation described for the PUT sim_cards/: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.

curl -X PUT \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"mobile_operator_networks_preferences":"array","sim_card_ids":["6b14e151-8493-4fa1-8664-1cc4e6d14158","6b14e151-8493-4fa1-8664-1cc4e6d14158"]}' \
  https://api.telnyx.com/v2/actions/network_preferences/sim_cards
Parameters
In body
mobile_operator_networks_preferences
array of object
optional

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

mobile_operator_network_id
string (uuid)

The mobile operator network resource identification UUID.

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

0
sim_card_ids
array of string
optional
Example: [ "6b14e151-8493-4fa1-8664-1cc4e6d14158", "6b14e151-8493-4fa1-8664-1cc4e6d14158" ]
Responses
202

422

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

Success Response
{
  "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"
    }
  ]
}
Previous: SIM Card Groups

Was this section helpful?was-this-page-helpful