# TelliSIM API v3 # API explanation ![API explanation diagram](https://cdn.tellisim.com/tellisim-website-images/tellisim-api-docs-diagram.png) Version: 1.0.0 ## Servers Production server ``` https://api.tellisim.com ``` ## Security ### ApiKeyAuth Your API key for authentication Type: apiKey In: query Name: key ## Download OpenAPI description [TelliSIM API v3](https://api-docs.tellisim.com/_bundle/openapi.yaml) ## Subscriptions Operations related to subscriptions. ### List Subscriptions - [GET /v3/subscription](https://api-docs.tellisim.com/openapi/subscriptions/kuy01agj9wxkq-list-subscriptions.md): 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. ### Create Subscriptions - [POST /v3/subscription](https://api-docs.tellisim.com/openapi/subscriptions/y0553xy7w914c-create-subscriptions.md): 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. ### Get a subscription - [GET /v3/subscriptions/{iccid}](https://api-docs.tellisim.com/openapi/subscriptions/9r03ycqqjdxez-get-a-subscription.md): 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. ### Delete a Subscription - [DELETE /v3/subscriptions/{iccid}](https://api-docs.tellisim.com/openapi/subscriptions/r5cdqtky0qde0-delete-a-subscription.md): 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. ### List plan attachments - [GET /v3/subscriptions/{iccid}/plan-attachments](https://api-docs.tellisim.com/openapi/subscriptions/urh0yrd5tx486-list-plan-attachments.md): This endpoint retrieves the plan attachments associated with a specific subscription identified by its ICCID. ### Get a plan attachment - [GET /v3/subscriptions/{iccid}/plan-attachments/{plan_id}](https://api-docs.tellisim.com/openapi/subscriptions/get-plan-attachment-by-id.md): This endpoint retrieves the details of a specific plan attachment for a subscription. ### Suspend a plan attachment - [POST /v3/subscriptions/{iccid}/plan-attachments/{id}/suspend](https://api-docs.tellisim.com/openapi/subscriptions/7vircgwk1k8dm-suspend-a-plan-attachment.md): This operation stops all telco services on this attachment and puts it in a suspended state. This is a non-reversible operation. ### Send sms - [POST /v3/subscriptions/{iccid}/send-sms](https://api-docs.tellisim.com/openapi/subscriptions/8znze4vr6c4v9-send-sms.md): 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. ### Get subscription location - [GET /v3/subscriptions/{iccid}/location](https://api-docs.tellisim.com/openapi/subscriptions/03nzews3r6c4v9-get-subscription-location.md): This endpoint retrieves the location information of a specific subscription associated with an eSIM, identified by its ICCID. It provides information about the last operator the SIM was connected to, including country, operator name, and technical details. Important: This endpoint only returns data if the SIM has been active in the last 7 days. If the SIM has not been active during this period, the last_operator field will be null. ### Get subscriber Geo-location - [GET /v3/subscriptions/{iccid}/geo-location](https://api-docs.tellisim.com/openapi/subscriptions/1jgedfw32323dd-get-subscriber-geo-location.md): This endpoint retrieves the geographic location data for a specific subscription identified by its ICCID. It provides the latitude, longitude, accuracy, and timestamp of the subscriber's last known location. Important notes: - This feature has limited availability and is not supported for all labels - Location data may be unavailable if the eSIM has not yet been activated or has no usage history - Even when usage exists, location information may not be available if it was not captured by the system The response includes: - Latitude and Longitude: Geographic coordinates of the last known position - Accuracy: The estimated median error in meters, representing the radius of a circle with 50% confidence level - Date and Time: Timestamp (UTC+0) indicating when the subscriber was last detected by the system ### Get usage over period - [POST /v3/subscriptions/{iccid}/usage-over-period](https://api-docs.tellisim.com/openapi/subscriptions/fwapp44dmnss-get-subscription-usage-over-period.md): This endpoint retrieves detailed usage data for a specific subscription identified by its ICCID over a specified time period. Important constraints: - The maximum period is 7 days, including both the start and end dates - The start date must come before the end date - Requests that violate these constraints will be rejected The response includes: - Total usage aggregated across the entire period - Daily breakdown of usage with country-level details - Country-level aggregation for the entire period ## Plans Operations related to plans. ### List plans - [GET /v3/plans](https://api-docs.tellisim.com/openapi/plans/roe63e3fhdeh5-list-plans.md): This endpoint retrieves a list of available plans. It allows users to specify pagination and filter out archived plans. ### Create Plans - [POST /v3/plans](https://api-docs.tellisim.com/openapi/plans/rsq2cu2wtponb-create-plans.md): Creates a plan with the given configuration. ### Get a Plan - [GET /v3/plans/{planId}](https://api-docs.tellisim.com/openapi/plans/8p6b2qv85fzoj-get-a-plan.md): Retrieves the details of an existing plan by its ID. ### Delete a Plan - [DELETE /v3/plans/{planId}](https://api-docs.tellisim.com/openapi/plans/delete-a-plan.md): Deletes plan with the given id. Deleting a plan won't impact the existing and historic attachments for this plan. They will continue to work as expected. ### Archive a plan - [POST /v3/plans/{planId}/archive](https://api-docs.tellisim.com/openapi/plans/2vx77nutyy4a1-archive-a-plan.md): This endpoint allows you to archive a specific plan identified by its planId. Archiving a plan may be necessary for managing your plans effectively, especially when they are no longer active or needed. ### Unarchive a plan - [POST /v3/plans/{planId}/unarchive](https://api-docs.tellisim.com/openapi/plans/3pax3wmtx0ckv-unarchive-a-plan.md): This endpoint allows you to unarchive a specific plan identified by its planId. When a plan is unarchived, it is restored to an active state, making it available for use again. ## Coverage Operations related to coverage. ### List coverage profiles - [GET /v3/coverage-profiles](https://api-docs.tellisim.com/openapi/coverage/xwappasg4mnsd-list-coverage-profiles.md): Returns the list of coverage profiles available to your account. ### Get the coverage profile - [GET /v3/coverage-profiles/{coverageId}](https://api-docs.tellisim.com/openapi/coverage/fltojr54olllm-get-the-coverage-profile.md): Retrieves the coverage profile ### Create custom region coverage profile - [POST /v3/coverage-profiles/custom-region](https://api-docs.tellisim.com/openapi/coverage/9dtoar54odjsm-create-custom-region-coverage-profile.md): Creates a custom region coverage profile using a list of ISO 2-letter country codes. Validation checks: The system performs the following validations before creating the profile: - Duplicate name check: If a region with the same name already exists for this organization, returns 400 Bad Request - Duplicate coverage check: If a coverage profile with the exact same set of countries already exists, returns 409 Conflict with the existing profile details Note: Coverage profiles are immutable and cannot be deleted. You can only create new profiles. ## SIM Operations related to SIM management. ### List SIMs - [GET /v3/sims](https://api-docs.tellisim.com/openapi/sim/s3rz0wvzvnuuz-list-sims.md): This endpoint retrieves a list of SIMs(both eSIMs and physical sim cards) associated with organization. ### Get SIM details - [GET /v3/sims/{iccid}](https://api-docs.tellisim.com/openapi/sim/xou0n7wvmb58j-get-sim-by-iccid.md): This endpoint retrieves the details of a specific SIM by its ICCID. ### Get SIM SMDP information - [GET /v3/sims/{iccid}/smdp-info](https://api-docs.tellisim.com/openapi/sim/ftvathnftu1cu-get-sim-smdp-info.md): This endpoint retrieves the SM-DP+ (Subscription Manager Data Preparation) information for a specific SIM by its ICCID. The response includes the state history of the eSIM profile with the following possible states: - BPP Installation: The process of downloading and installing the eSIM profile via a Bootstrap Provisioning Platform (BPP) - Enable: eSIM is switched on from device settings, allowing it to connect to the mobile network - Disable: eSIM is turned off via device settings, temporarily preventing it from being used - Delete: eSIM profile is completely removed from the device ## Operators Operations related to operators. ### List operators - [GET /v3/operators](https://api-docs.tellisim.com/openapi/operators/u8ed9w0ej2nj4-list-operators.md): Returns the list of operators filtered by optional label and country filters. ### Get operator - [GET /v3/operators/{operatorId}](https://api-docs.tellisim.com/openapi/operators/9ej4esdkfjfe9-get-operator.md): Retrieves the details of a specific operator. ## Webhook Events Operations related to webhook events. ### 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: ```ts import * as tellisimSignatureValidator from '@tellisim/webhook-signature-validator'; tellisimSignatureValidator.validate(signature, signingKey, webhookDataObject); ``` Field type | Description --- | --- signature | The header received in `x-tellisim-signature` field. signingKey | The signing key configured for your webhooks. webhookDataObject | The JSON payload received in the webhook call. ### Data allowance consumed - [POST attachment.allowanceConsumed](https://api-docs.tellisim.com/openapi/webhook-events/attachment-allowance-consumed.md): Triggered when 50%, 80%, or 100% of a fixed validity plan's data allowance is consumed (no events for recurring plans). ### SIM location changed - [POST subscription.esim.locationChanged](https://api-docs.tellisim.com/openapi/webhook-events/subscription-esim-location-changed.md): Triggered when a SIM's country location changes. ### SIM SMDP Status Changed - [POST esim.smdp.stateChanged](https://api-docs.tellisim.com/openapi/webhook-events/esim-smdp-state-changed.md): The event is sent whenever the SMDP state of an event is changed.