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

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

Validate webhook signature

Each webhook call generated from TelliSIM includes a unique signature header to validate call authenticity.

The webhook contains a header x-tellisim-signature which identifies the call signature for each user.

To validate the signature, you can use the official npm library:

  • @tellisim/webhook-signature-validator
    https://www.npmjs.com/package/@tellisim/webhook-signature-validator

Basic usage:

import * as tellisimSignatureValidator from '@tellisim/webhook-signature-validator';

tellisimSignatureValidator.validate(signature, signingKey, webhookDataObject);
Field typeDescription
signatureThe header received in x-tellisim-signature field.
signingKeyThe signing key configured for your webhooks.
webhookDataObjectThe JSON payload received in the webhook call.

Data allowance consumedWebhook

Request

Triggered when 50%, 80%, or 100% of a fixed validity plan's data allowance is consumed (no events for recurring plans).

Security
ApiKeyAuth
Bodyapplication/json
typestringrequired
Example: "attachment.allowanceConsumed"
timestampintegerrequired

Unix timestamp when the event was fired

Example: 1730474606
dataobjectrequired
data.​usagePercentagenumber[ 0 .. 100 ]required

Percentage of data allowance consumed

Example: 80
data.​dataUsageBytesnumberrequired

Data consumed in bytes

Example: 1231230
data.​esimstringrequired

The eSIM or physical SIM identifier

Example: "8937103400004164763"
data.​planIdstringrequired

The plan identifier

Example: "33de44b0-5103-45ea-9723-0a7aa104c76a"
data.​attachmentIdstringrequired

The attachment identifier

Example: "a1ac5a45-e05b-4728-9253-17c54fc1c5ff"
application/json
{
  "type": "attachment.allowanceConsumed",
  "timestamp": 1730474606,
  "data": {
    "usagePercentage": 80,
    "dataUsageBytes": 1231230,
    "esim": "8937103400004164763",
    "planId": "33de44b0-5103-45ea-9723-0a7aa104c76a",
    "attachmentId": "a1ac5a45-e05b-4728-9253-17c54fc1c5ff"
  }
}

Responses

Return a 200 status to indicate that the data was received successfully

SIM location changedWebhook

Request

Triggered when a SIM's country location changes.

Security
ApiKeyAuth
Bodyapplication/json
typestringrequired
Example: "subscription.esim.locationChanged"
timestampintegerrequired

Unix timestamp when the event was fired

Example: 1759429928
dataobjectrequired
data.​esimstringrequired

The eSIM or physical SIM identifier

Example: "8937204017179541233"
data.​countryIso2stringrequired

ISO 2-letter country code

Example: "IT"
application/json
{
  "type": "subscription.esim.locationChanged",
  "timestamp": 1759429928,
  "data": {
    "esim": "8937204017179541233",
    "countryIso2": "IT"
  }
}

Responses

Return a 200 status to indicate that the data was received successfully

SIM SMDP Status ChangedWebhook

Request

The event is sent whenever the SMDP state of an event is changed.

Security
ApiKeyAuth
Bodyapplication/json
typestringrequired
Example: "esim.smdp.stateChanged"
timestampintegerrequired

Unix timestamp when the event was fired

Example: 1761991449
dataobjectrequired
data.​simstringrequired

The eSIM or physical SIM identifier

Example: "8937204017179541233"
data.​smdpStateChangeobjectrequired
data.​smdpStateChange.​statestringrequired

The SMDP state

Enum"BPP Installation""Enable""Disable""Delete"
Example: "Enable"
data.​smdpStateChange.​modificationResultstringrequired

The result of the state modification

Example: "SUCCESS"
application/json
{
  "type": "esim.smdp.stateChanged",
  "timestamp": 1761991449,
  "data": {
    "sim": "8937204017179541233",
    "smdpStateChange": { … }
  }
}

Responses

Return a 200 status to indicate that the data was received successfully