Skip to content

TelliSIM API v3 (1.0.0)

API explanation

API explanation diagram

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Languages
Servers
Production server
https://api.tellisim.com/

Subscriptions

Operations related to subscriptions.

Operations

List Subscriptions

Request

This endpoint allows users to retrieve subscription details associated with the SIM service. It provides information about the subscription, including its ID, creation date, associated metadata, and SIM details.

Security
ApiKeyAuth
curl -i -X GET \
  'https://api.tellisim.com/v3/subscription?key=YOUR_API_KEY_HERE'

Responses

Successful response containing subscription details

Bodyapplication/json
errorbooleanrequired

Indicates whether there was an error in the request

Example: false
dataArray of objectsrequired

Contains an array of subscription objects

data[].​subscription_idstringrequired

The unique identifier for the subscription

Example: "6174d2d5-f3bd-4336-abe0-13d75cc8a023"
data[].​created_atstringrequired

The timestamp when the subscription was created

Example: "2025-08-24T14:59:38.037Z"
data[].​metadatastringrequired

Additional metadata related to the subscription

Example: "usa plan applied"
data[].​esimobjectrequired
data[].​esim.​esim_idstringrequired

The unique identifier for the eSIM

Example: "67940632-e09e-4c16-b220-1b47988d50b6"
data[].​esim.​iccidstringrequired

The Integrated Circuit Card Identifier for the eSIM

Example: "8948010000031324500"
data[].​esim.​lpa_stringstring or null

The LPA string associated with the eSIM if it is an eSIM else null.

Example: "LPA:1$smdp.io$K2-2GNHV6-USUV2O"
data[].​esim.​labelstringrequired

A label for the eSIM

Example: "Green"
Response
application/json
{
  "error": false,
  "data": [
    { … }
  ]
}

Create Subscriptions

Request

This endpoint allows users to create a new subscription for a SIM. By sending a POST request to the specified URL, users can initiate the subscription process with the necessary parameters. The optional active_period field controls when the subscription becomes active and (optionally) when it expires.

Security
ApiKeyAuth
Bodyapplication/json
iccidstring

ICCID of the SIM (eSIM or Physical SIM). If not provided, the API will automatically select a free eSIM for the specified plan label. If no free eSIM is available for that label, a 404 error will be returned.

Example: "8948010000031324502"
metadatastringrequired
Example: "usa recurring plan"
plan_idstringrequired
Example: "0a3ee1d6-fe5e-4561-91a0-d4649aaf0754"
active_periodobject or null

Optional activation window for the subscription.

Non‑recurring plans

  • active_period is optional.
  • When active_period is provided, both start and end are required.
  • The start and end values are used as the start and end date and time for the active period of the package and override any validity period configured in the package template.
  • When active_period is not provided, the package uses the default behavior: activation at first use.

Recurring plans

  • active_period is optional.
  • When active_period is provided, start is required and end is optional.
  • If active_period is not provided, the recurring subscription also uses the default behavior: activation at first use.

When a Start date is provided for a recurring plan:

  • Start date in the past (maximum 24 hours): the first subscriber package is created immediately.
  • Start date in the future but within the next 12 hours: the first subscriber package is also created immediately.
  • Start date more than 12 hours in the future: no subscriber package is created immediately; the first subscriber package will be created by the system 12 hours before its activation time.
curl -i -X POST \
  'https://api.tellisim.com/v3/subscription?key=YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "iccid": "8948010000031324502",
    "metadata": "usa recurring plan",
    "plan_id": "0a3ee1d6-fe5e-4561-91a0-d4649aaf0754",
    "active_period": {
      "start": "2025-12-10T15:03:28.533603",
      "end": "2025-12-20T15:03:28.533603"
    }
  }'

Responses

Subscription created successfully

Bodyapplication/json
subscription_idstringrequired

The unique identifier for the created subscription

Example: "a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64"
created_atstringrequired

Timestamp indicating when the subscription was created

Example: "2025-08-08T11:05:57.703Z"
activation_atstring or null(date-time)

Present only when active_period was provided in the request. The value reflects the actual activation time reported by the underlying system when available. If the underlying system does not return an activation timestamp, the API falls back to active_period.start. This field is omitted entirely if active_period was not sent.

Example: "2025-12-10T15:03:28.533603Z"
expiration_atstring or null(date-time)

Present only when active_period was provided in the request. The value reflects the actual expiration time reported by the underlying system when available. If the underlying system does not return an expiration timestamp, the API falls back to active_period.end when provided; otherwise it remains null. This field is omitted entirely if active_period was not sent.

Example: "2025-12-20T15:03:28.533603Z"
metadatastringrequired

The metadata provided in the request

Example: "usa recurring plan"
esimdataobjectrequired

An object containing details about the eSIM or Physical SIM

esimdata.​esim_idstringrequired

The unique identifier for the eSIM

Example: "65a89dca-349e-4278-95fb-a8fe2e9b281f"
esimdata.​iccidstringrequired

The Integrated Circuit Card Identifier for the eSIM

Example: "8937103400004164763"
esimdata.​labelstringrequired

A label associated with the eSIM

Example: "blue"
esimdata.​lpa_stringstring or null

The LPA string associated with the eSIM

Example: "LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C"
Response
application/json
{
  "subscription_id": "a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64",
  "created_at": "2025-08-08T11:05:57.703Z",
  "activation_at": "2025-12-10T15:03:28.533603Z",
  "expiration_at": "2025-12-20T15:03:28.533603Z",
  "metadata": "usa recurring plan",
  "esimdata": {
    "esim_id": "65a89dca-349e-4278-95fb-a8fe2e9b281f",
    "iccid": "8937103400004164763",
    "label": "blue",
    "lpa_string": "LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C"
  }
}

Get a subscription

Request

This endpoint retrieves the details of a specific subscription associated with an eSIM, identified by its ICCID. It provides information such as the subscription ID, creation date, metadata, and SIM or Physical SIM details.

Security
ApiKeyAuth
Path
iccidstringrequired
curl -i -X GET \
  'https://api.tellisim.com/v3/subscriptions/{iccid}?key=YOUR_API_KEY_HERE'

Responses

Successful response containing subscription details

Bodyapplication/json
errorbooleanrequired

Indicates whether there was an error processing the request

Example: false
dataobjectrequired

Contains the details of the subscription

data.​subscription_idstringrequired

The unique identifier for the subscription

Example: "38838e12-4394-4e04-bb11-9250e835668e"
data.​created_atstringrequired

The timestamp when the subscription was created

Example: "2025-08-17T15:16:00.890Z"
data.​metadatastringrequired

Additional metadata related to the subscription

Example: "Subscription for USA"
data.​esimobjectrequired

Contains details about the SIM

data.​esim.​esim_idstringrequired

The unique identifier for the SIM(eSIM or Physical SIM)

Example: "5a15183b-ca25-4725-b8a8-807990f98e03"
data.​esim.​iccidstringrequired

The ICCID of the SIM(eSIM or Physical SIM)

Example: "8937103400004164763"
data.​esim.​lpa_stringstring or null

The LPA string associated with the eSIM else null for physical SIM

Example: "LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C"
data.​esim.​labelstringrequired

A label for the SIM

Example: "blue"
Response
application/json
{
  "error": false,
  "data": {
    "subscription_id": "38838e12-4394-4e04-bb11-9250e835668e",
    "created_at": "2025-08-17T15:16:00.890Z",
    "metadata": "Subscription for USA",
    "esim": { … }
  }
}

Delete a Subscription

Request

Deletes the subscription and recycles the ICCID associated with it. The associated ICCID goes back into the customer inventory and will be picked up again automatically in the creation of a new subscription at some point in time in future.

Note: this operation will fail if the esim profile associated with the ICCID was ever downloaded by an end-user.

Security
ApiKeyAuth
Path
iccidstringrequired
curl -i -X DELETE \
  'https://api.tellisim.com/v3/subscriptions/{iccid}?key=YOUR_API_KEY_HERE'

Responses

Subscription deleted successfully

Bodyapplication/json
errorbooleanrequired

A boolean indicating whether there was an error in the request

Example: false
messagestringrequired

A message indicating the result of the delete operation

Example: "Subscription deleted successfully"
Response
application/json
{
  "error": false,
  "message": "Subscription deleted successfully"
}

List plan attachments

Request

This endpoint retrieves the plan attachments associated with a specific subscription identified by its ICCID.

Security
ApiKeyAuth
Path
iccidstringrequired
curl -i -X GET \
  'https://api.tellisim.com/v3/subscriptions/{iccid}/plan-attachments?key=YOUR_API_KEY_HERE'

Responses

Successful response containing plan attachments

Bodyapplication/json
errorbooleanrequired

A boolean indicating whether there was an error in the request

Example: false
dataArray of objectsrequired

An array containing details of the plan attachments

data[].​plan_attachment_idstringrequired

The unique identifier for the plan attachment

Example: "efff707e-7db0-4ffe-bef9-5817cabcba3b"
data[].​created_atstringrequired

The timestamp when the plan attachment was created

Example: "2025-08-17T15:15:59.000Z"
data[].​activation_atstring or null

The timestamp when the plan attachment was activated (may be null)

Example: "2025-08-17T15:15:59.000Z"
data[].​expiration_atstring or null

The timestamp when the plan attachment will expire (may be null)

Example: "2025-08-17T15:15:59.000Z"
data[].​used_allowanceobjectrequired

An object containing usage details

data[].​used_allowance.​dataBytesnumberrequired

The amount of data used in bytes

Example: 100
data[].​statestringrequired

The current state of the plan attachment

Enum"PENDING_FOR_FIRST_USE""CREATED""ACTIVE""SUSPENDED""EXPIRED"
Example: "ACTIVE"
data[].​planobjectrequired

The plan details associated with this attachment

data[].​plan.​namestring

The name of the plan

Example: "Usa plan green 1gb 7 days"
data[].​plan.​_idstring(uuid)

The unique identifier for the plan

Example: "e90b8df8-fc8a-4010-8d70-13c756017747"
data[].​plan.​coverage_idstring(uuid)

The unique identifier for the coverage area

Example: "24648a7f-8281-4af7-8fc0-19b2371b2d1d"
data[].​plan.​region_codestring

The region code for the plan

Example: "US"
data[].​plan.​labelstring

The label or tier of the plan

Example: "Green"
data[].​plan.​throttlingboolean

Indicates whether throttling is enabled for this plan

Example: false
data[].​plan.​recurringboolean

Indicates whether this is a recurring plan

Example: false
data[].​plan.​data_mega_bytesinteger

The data allowance in megabytes

Example: 1024
data[].​plan.​period_daysinteger

The duration of the plan in days

Example: 7
Response
application/json
{
  "error": false,
  "data": [
    { … }
  ]
}

Get a plan attachment

Request

This endpoint retrieves the details of a specific plan attachment for a subscription.

Security
ApiKeyAuth
Path
iccidstringrequired
plan_idstringrequired
curl -i -X GET \
  'https://api.tellisim.com/v3/subscriptions/{iccid}/plan-attachments/{plan_id}?key=YOUR_API_KEY_HERE'

Responses

Successful response containing the plan attachment details.

Bodyapplication/json
errorboolean
dataobject(PlanAttachment)
Response
application/json
{
  "error": true,
  "data": {
    "plan_attachment_id": "ba3b527f-4a01-42e2-892a-fff6d217217e",
    "created_at": "2025-08-30T08:00:18.681Z",
    "activation_at": "2025-08-30T08:00:18.681Z",
    "expiration_at": "2025-08-30T08:00:18.681Z",
    "used_allowance": { … },
    "state": "CREATED",
    "plan": { … }
  }
}

Suspend a plan attachment

Request

This operation stops all telco services on this attachment and puts it in a suspended state. This is a non-reversible operation.

Security
ApiKeyAuth
Path
iccidstringrequired
idstringrequired
curl -i -X POST \
  'https://api.tellisim.com/v3/subscriptions/{iccid}/plan-attachments/{id}/suspend?key=YOUR_API_KEY_HERE'

Responses

Plan attachment suspended successfully

Bodyapplication/json
errorbooleanrequired

A boolean indicating whether an error occurred during the request

Example: false
messagestringrequired

A string containing any error message, if applicable

Example: "Plan attachment suspended successfully"
Response
application/json
{
  "error": false,
  "message": "Plan attachment suspended successfully"
}

Send sms

Request

This endpoint allows you to send an SMS message to a specified eSIM subscription identified by its ICCID. The request requires an API key for authentication and includes parameters for the sender's name and the message content.

Security
ApiKeyAuth
Path
iccidstringrequired
Bodyapplication/json
fromstringrequired
Example: "tellisim"
messagestringrequired
Example: "test message"
curl -i -X POST \
  'https://api.tellisim.com/v3/subscriptions/{iccid}/send-sms?key=YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "tellisim",
    "message": "test message"
  }'

Responses

SMS sent successfully

Bodyapplication/json
errorbooleanrequired

Indicates whether an error occurred (true if an error occurred)

Example: false
messagestringrequired

A message providing additional information about the success response

Example: "SMS sent successfully"
Response
application/json
{
  "error": false,
  "message": "SMS sent successfully"
}

Plans

Operations related to plans.

Operations

Coverage

Operations related to coverage.

Operations

SIM

Operations related to SIM management.

Operations

Operators

Operations related to operators.

Operations

Webhook Events

Operations related to webhook events.

Webhooks