openapi: 3.1.0
info:
  title: TelliSIM API v3
  contact: {}
  version: 1.0.0
  description: >
    # API explanation


    ![API explanation
    diagram](https://cdn.tellisim.com/tellisim-website-images/v3-portal-explainer-diagram.jpg)
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: Your API key for authentication
  schemas:
    CoverageProfile:
      type: object
      properties:
        coverage_id:
          type: string
          description: The unique identifier for the coverage profile
          example: 24648a7f-8281-4af7-8fc0-19b2371b2d1d
        label:
          type: string
          description: The label for the coverage profile
          example: Green
        region_name:
          type: string
          description: The name of the region for which the coverage is applicable
          example: United States
        region_code:
          type: string
          description: The ISO code of the region for which the coverage is applicable
          example: US
        countries:
          type: array
          description: Optional list of countries included in this coverage profile
          items:
            type: object
            properties:
              iso2:
                type: string
                description: ISO 2-letter country code
                example: US
              iso3:
                type: string
                description: ISO 3-letter country code
                example: USA
              name:
                type: string
                description: Country name
                example: United States
              operators:
                type: array
                description: >-
                  Optional list of operators available in this country for the
                  coverage profile
                items:
                  type: object
                  properties:
                    operator_id:
                      type: string
                      description: The unique identifier for the operator
                      example: 2dea792a-2dea-492c-815d-8fb826be8d49
                    name:
                      type: string
                      description: The name of the operator
                      example: AT&T USA
                    supported_rats:
                      type: array
                      description: List of supported Radio Access Technologies (RATs)
                      items:
                        type: string
                      example:
                        - 4G
                        - 5G
                    mcc_mnc:
                      type: array
                      description: List of MCC-MNC codes associated with the operator
                      items:
                        type: string
                      example:
                        - 310-680
                        - 310-410
      required:
        - coverage_id
        - label
        - region_name
        - region_code
    Plan:
      type: object
      properties:
        plan_name:
          type: string
          description: Name of the plan
          example: USA Plan
        plan_id:
          type: string
          description: Unique identifier for the plan
          example: 39c3ae26-22a5-49cb-93ca-2fe65b3a5c69
        coverage_id:
          type: string
          description: Identifier for the coverage area of the plan
          example: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
        archived_at:
          type:
            - string
            - 'null'
          description: Timestamp of when the plan was archived (if applicable)
          example: null
        region_code:
          type: string
          description: Code representing the region for the plan
          example: US
        label:
          type: string
          description: Label for the plan
          example: blue
        created_at:
          type: string
          description: Timestamp of when the plan was created
          example: '2025-01-01T00:00:00Z'
        throttling:
          type: boolean
          description: Indicates if the plan has throttling enabled
          example: true
        recurring:
          type: boolean
          description: Indicates if the plan is recurring
          example: true
        data_mega_bytes:
          type: integer
          description: Amount of data in megabytes included in the plan
          example: 1024
        period_days:
          type: integer
          description: Duration of the plan in days
          example: 30
        archive:
          type: boolean
          description: Indicates if the plan is archived
          example: false
        period_iterations:
          type: integer
          description: Number of iterations for the plan period
          example: 12
        throttling_threshold1_perc:
          type: integer
          description: The percentage threshold for first throttling
          example: 50
          minimum: 0
          maximum: 100
        throttling_threshold1_limit:
          type: string
          description: The limit associated with the first throttling threshold
          example: '3072'
          enum:
            - '32'
            - '64'
            - '128'
            - '256'
            - '384'
            - '512'
            - '1024'
            - '3072'
            - '5120'
            - '7680'
            - '10240'
            - '20480'
        throttling_threshold2_perc:
          type: integer
          description: The percentage threshold for second throttling
          example: 80
          minimum: 0
          maximum: 100
        throttling_threshold2_limit:
          type: string
          description: The limit associated with the second throttling threshold
          example: '384'
          enum:
            - '32'
            - '64'
            - '128'
            - '256'
            - '384'
            - '512'
            - '1024'
            - '3072'
            - '5120'
            - '7680'
            - '10240'
            - '20480'
        throttling_threshold3_perc:
          type: integer
          description: The percentage threshold for third throttling
          example: 90
          minimum: 0
          maximum: 100
        throttling_threshold3_limit:
          type: string
          description: The limit associated with the third throttling threshold
          example: '128'
          enum:
            - '32'
            - '64'
            - '128'
            - '256'
            - '384'
            - '512'
            - '1024'
            - '3072'
            - '5120'
            - '7680'
            - '10240'
            - '20480'
        nb_occurrence:
          type: integer
          description: The number of occurrences for the plan
          example: 12
        recurring_periodicity_type:
          type: string
          description: >-
            The type of periodicity for the recurring plan. Possible values are
            0=Daily, 1=Weekly, 2=Monthly.
          example: '0'
          enum:
            - '0'
            - '1'
            - '2'
        recurring_periodicity_frequency:
          type: integer
          description: The frequency of the recurring billing cycle
          example: 1
      required:
        - plan_id
        - coverage_id
        - label
        - data_mega_bytes
        - period_days
        - archived_at
        - region_code
        - created_at
        - throttling
        - recurring
        - archive
        - plan_name
    ESIM:
      type: object
      properties:
        iccid:
          type: string
          description: The Integrated Circuit Card Identifier of the eSIM
          example: '8937103400004164763'
        label:
          type: string
          description: A label for the eSIM
          example: Blue
        lpa:
          type:
            - string
            - 'null'
          description: >-
            The Local Profile Assistant associated with the eSIM if the SIM is
            an eSIM
          example: LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C
        used:
          type: boolean
          description: Indicates if the SIM has been used or not
          example: false
        esim_id:
          type: string
          description: The unique identifier for the eSIM
          example: 5a15183b-ca25-4725-b8a8-807990f98e03
        created_at:
          type: string
          format: date-time
          description: The timestamp when the SIM was created
          example: '2025-08-11T14:43:15.761Z'
        is_esim:
          type: boolean
          description: Indicates if the item is an eSIM or not
          example: true
      required:
        - iccid
        - esim_id
        - is_esim
        - created_at
        - label
    ESIMListResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: false
        data:
          type: array
          description: Contains an array of SIM objects
          items:
            $ref: '#/components/schemas/ESIM'
        next_page:
          type:
            - string
            - 'null'
          description: >-
            A token for pagination, indicating if there are more results
            available
          example: MQ==
      required:
        - error
        - data
        - next_page
    PlanListResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates if there was an error in the request
          example: false
        data:
          type: array
          description: An array of plan objects returned by the request
          items:
            $ref: '#/components/schemas/Plan'
        next_page:
          type:
            - string
            - 'null'
          description: Token for the next page of results, if available
          example: null
      required:
        - error
        - data
        - next_page
    PlanCreateResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates if there was an error processing the request
          example: false
        message:
          type: string
          description: A message providing additional information about the error (if any)
          example: plan created successfully
        plan_id:
          type: string
          description: The unique identifier for the newly created plan (if successful)
          example: 39c3ae26-22a5-49cb-93ca-2fe65b3a5c69
      required:
        - error
        - message
        - plan_id
    Subscription:
      type: object
      properties:
        subscription_id:
          type: string
          description: The unique identifier for the subscription
          example: a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64
        created_at:
          type: string
          description: The timestamp when the subscription was created
          example: '2025-08-08T11:05:57.703'
        activation_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            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`.

            When `active_period` is **not** sent, the subscription uses the
            default behavior (activation at first use) and this field is omitted
            from the response.
          example: '2025-12-10T15:03:28.533603'
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            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 it is provided (typically for
              non-recurring plans), or
            - the underlying plan validity when `end` is omitted (typically
              for recurring plans where only a `start` is sent).

            When `active_period` is **not** sent, the subscription uses the
            default behavior (activation at first use) and this field is omitted
            from the response.
          example: '2025-12-20T15:03:28.533603Z'
        metadata:
          type: string
          description: Additional metadata related to the subscription
          example: test message
        esim:
          $ref: '#/components/schemas/ESIM'
      required:
        - subscription_id
        - created_at
        - esim
    SubscriptionListResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether there was an error in the request
          example: false
        data:
          type: array
          description: Contains an array of subscription objects
          items:
            type: object
            properties:
              subscription_id:
                type: string
                description: The unique identifier for the subscription
                example: 6174d2d5-f3bd-4336-abe0-13d75cc8a023
              created_at:
                type: string
                description: The timestamp when the subscription was created
                example: '2025-08-24T14:59:38.037Z'
              metadata:
                type: string
                description: Additional metadata related to the subscription
                example: usa plan applied
              esim:
                type: object
                properties:
                  esim_id:
                    type: string
                    description: The unique identifier for the eSIM
                    example: 67940632-e09e-4c16-b220-1b47988d50b6
                  iccid:
                    type: string
                    description: The Integrated Circuit Card Identifier for the eSIM
                    example: '8948010000031324500'
                  lpa_string:
                    type:
                      - string
                      - 'null'
                    description: >-
                      The LPA string associated with the eSIM if it is an eSIM
                      else null.
                    example: LPA:1$smdp.io$K2-2GNHV6-USUV2O
                  label:
                    type: string
                    description: A label for the eSIM
                    example: Green
                required:
                  - esim_id
                  - iccid
                  - label
            required:
              - subscription_id
              - created_at
              - metadata
              - esim
      required:
        - error
        - data
    SubscriptionCreateResponse:
      type: object
      properties:
        subscription_id:
          type: string
          description: The unique identifier for the created subscription
          example: a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64
        created_at:
          type: string
          description: Timestamp indicating when the subscription was created
          example: '2025-08-08T11:05:57.703Z'
        activation_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            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_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >
            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'
        metadata:
          type: string
          description: The metadata provided in the request
          example: usa recurring plan
        esimdata:
          type: object
          description: An object containing details about the eSIM or Physical SIM
          properties:
            esim_id:
              type: string
              description: The unique identifier for the eSIM
              example: 65a89dca-349e-4278-95fb-a8fe2e9b281f
            iccid:
              type: string
              description: The Integrated Circuit Card Identifier for the eSIM
              example: '8937103400004164763'
            label:
              type: string
              description: A label associated with the eSIM
              example: blue
            lpa_string:
              type:
                - string
                - 'null'
              description: The LPA string associated with the eSIM
              example: LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C
          required:
            - esim_id
            - iccid
            - label
      required:
        - subscription_id
        - created_at
        - metadata
        - esimdata
    SubscriptionDetailResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether there was an error processing the request
          example: false
        data:
          type: object
          description: Contains the details of the subscription
          properties:
            subscription_id:
              type: string
              description: The unique identifier for the subscription
              example: 38838e12-4394-4e04-bb11-9250e835668e
            created_at:
              type: string
              description: The timestamp when the subscription was created
              example: '2025-08-17T15:16:00.890Z'
            metadata:
              type: string
              description: Additional metadata related to the subscription
              example: Subscription for USA
            esim:
              type: object
              description: Contains details about the SIM
              properties:
                esim_id:
                  type: string
                  description: The unique identifier for the SIM(eSIM or Physical SIM)
                  example: 5a15183b-ca25-4725-b8a8-807990f98e03
                iccid:
                  type: string
                  description: The ICCID of the SIM(eSIM or Physical SIM)
                  example: '8937103400004164763'
                lpa_string:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The LPA string associated with the eSIM else null for
                    physical SIM
                  example: >-
                    LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C
                label:
                  type: string
                  description: A label for the SIM
                  example: blue
              required:
                - esim_id
                - iccid
                - label
          required:
            - subscription_id
            - created_at
            - metadata
            - esim
      required:
        - error
        - data
    DeleteResponse:
      type: object
      properties:
        error:
          type: boolean
          description: A boolean indicating whether there was an error in the request
          example: false
        message:
          type: string
          description: A message indicating the result of the delete operation
          example: Subscription deleted successfully
      required:
        - error
        - message
    PlanAttachmentListResponse:
      type: object
      properties:
        error:
          type: boolean
          description: A boolean indicating whether there was an error in the request
          example: false
        data:
          type: array
          description: An array containing details of the plan attachments
          items:
            type: object
            properties:
              plan_attachment_id:
                type: string
                description: The unique identifier for the plan attachment
                example: efff707e-7db0-4ffe-bef9-5817cabcba3b
              created_at:
                type: string
                description: The timestamp when the plan attachment was created
                example: '2025-08-17T15:15:59.000Z'
              activation_at:
                type:
                  - string
                  - 'null'
                description: >-
                  The timestamp when the plan attachment was activated (may be
                  null)
                example: '2025-08-17T15:15:59.000Z'
              expiration_at:
                type:
                  - string
                  - 'null'
                description: >-
                  The timestamp when the plan attachment will expire (may be
                  null)
                example: '2025-08-17T15:15:59.000Z'
              used_allowance:
                type: object
                description: An object containing usage details
                properties:
                  dataBytes:
                    type: number
                    description: The amount of data used in bytes
                    example: 100
                required:
                  - dataBytes
              state:
                type: string
                description: The current state of the plan attachment
                enum:
                  - PENDING_FOR_FIRST_USE
                  - CREATED
                  - ACTIVE
                  - SUSPENDED
                  - EXPIRED
                example: ACTIVE
              plan:
                type: object
                description: The plan details associated with this attachment
                properties:
                  name:
                    type: string
                    description: The name of the plan
                    example: Usa plan green 1gb 7 days
                  _id:
                    type: string
                    format: uuid
                    description: The unique identifier for the plan
                    example: e90b8df8-fc8a-4010-8d70-13c756017747
                  coverage_id:
                    type: string
                    format: uuid
                    description: The unique identifier for the coverage area
                    example: 24648a7f-8281-4af7-8fc0-19b2371b2d1d
                  region_code:
                    type: string
                    description: The region code for the plan
                    example: US
                  label:
                    type: string
                    description: The label or tier of the plan
                    example: Green
                  throttling:
                    type: boolean
                    description: Indicates whether throttling is enabled for this plan
                    example: false
                  recurring:
                    type: boolean
                    description: Indicates whether this is a recurring plan
                    example: false
                  data_mega_bytes:
                    type: integer
                    description: The data allowance in megabytes
                    example: 1024
                  period_days:
                    type: integer
                    description: The duration of the plan in days
                    example: 7
            required:
              - plan_attachment_id
              - created_at
              - used_allowance
              - state
              - plan
      required:
        - error
        - data
    PlanAttachmentDetailResponse:
      type: object
      properties:
        error:
          type: boolean
        data:
          $ref: '#/components/schemas/PlanAttachment'
    SMSResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred (true if an error occurred)
          example: false
        message:
          type: string
          description: >-
            A message providing additional information about the success
            response
          example: SMS sent successfully
      required:
        - error
        - message
    SuspendResponse:
      type: object
      properties:
        error:
          type: boolean
          description: A boolean indicating whether an error occurred during the request
          example: false
        message:
          type: string
          description: A string containing any error message, if applicable
          example: Plan attachment suspended successfully
      required:
        - error
        - message
    ArchiveResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether there was an error processing the request
          example: false
        message:
          type: string
          description: A message providing additional information about the request status
          example: Plan archived successfully
      required:
        - error
        - message
    PlanDetailResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: false
        data:
          type: object
          description: Contains the details of the requested plan
          properties:
            plan_name:
              type: string
              description: Name of the plan
              example: USA Plan
            plan_id:
              type: string
              description: The unique identifier of the plan
              example: 0a3ee1d6-fe5e-4561-91a0-d4649aaf0754
            coverage_id:
              type: string
              description: The ID associated with the plan's coverage
              example: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
            archived_at:
              type:
                - string
                - 'null'
              description: Timestamp indicating when the plan was archived, if applicable
              example: '2025-01-01T00:00:00Z'
            region_code:
              type: string
              description: The code representing the region for the plan
              example: US
            label:
              type: string
              description: A human-readable label for the plan
              example: blue
            throttling:
              type: boolean
              description: Indicates if throttling is applied to the plan
              example: true
            recurring:
              type: boolean
              description: Indicates if the plan has a recurring billing cycle
              example: true
            archive:
              type: boolean
              description: Indicates if the plan is archived
              example: true
            data_mega_bytes:
              type: integer
              description: The amount of data in megabytes included in the plan
              example: 1024
            period_days:
              type: integer
              description: The duration of the plan in days
              example: 1
            throttling_threshold1_perc:
              type: integer
              description: The percentage threshold for first throttling
              example: 10
              minimum: 0
              maximum: 100
            throttling_threshold1_limit:
              type: string
              description: The limit associated with the first throttling threshold
              example: '3072'
              enum:
                - '32'
                - '64'
                - '128'
                - '256'
                - '384'
                - '512'
                - '1024'
                - '3072'
                - '5120'
                - '7680'
                - '10240'
                - '20480'
            throttling_threshold2_perc:
              type: integer
              description: The percentage threshold for second throttling
              example: 10
              minimum: 0
              maximum: 100
            throttling_threshold2_limit:
              type: string
              description: The limit associated with the second throttling threshold
              example: '3072'
              enum:
                - '32'
                - '64'
                - '128'
                - '256'
                - '384'
                - '512'
                - '1024'
                - '3072'
                - '5120'
                - '7680'
                - '10240'
                - '20480'
            throttling_threshold3_perc:
              type: integer
              description: The percentage threshold for third throttling
              example: 10
              minimum: 0
              maximum: 100
            throttling_threshold3_limit:
              type: string
              description: The limit associated with the third throttling threshold
              example: '3072'
              enum:
                - '32'
                - '64'
                - '128'
                - '256'
                - '384'
                - '512'
                - '1024'
                - '3072'
                - '5120'
                - '7680'
                - '10240'
                - '20480'
            nb_occurrence:
              type: integer
              description: The number of occurrences for the plan
              example: 2
            recurring_periodicity_type:
              type: string
              description: >-
                The type of periodicity for the recurring plan. Possible values
                are 0=Daily, 1=Weekly, 2=Monthly.
              example: '2'
            recurring_periodicity_frequency:
              type: integer
              description: The frequency of the recurring billing cycle
              example: 0
          required:
            - plan_id
            - coverage_id
            - region_code
            - label
            - throttling
            - recurring
            - archive
            - data_mega_bytes
            - period_days
            - archived_at
            - plan_name
      required:
        - error
        - data
    UnauthorizedResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: true
        message:
          type: string
          description: Error message describing the unauthorized access
          example: 'Unauthorized: API key is missing'
      required:
        - error
        - message
    WebhookEvent:
      type: object
      required:
        - type
        - timestamp
        - data
      properties:
        type:
          type: string
          description: The type of webhook event
          example: attachment.allowanceConsumed
        timestamp:
          type: integer
          description: The unix timestamp at which this event was fired
          example: 1730474606
        data:
          type: object
          description: Event-specific data payload
    AllowanceConsumedEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            type:
              type: string
              default: attachment.allowanceConsumed
              example: attachment.allowanceConsumed
            data:
              type: object
              required:
                - usagePercentage
                - dataUsageBytes
                - esim
                - planId
                - attachmentId
              properties:
                usagePercentage:
                  type: number
                  minimum: 0
                  maximum: 100
                  description: The percentage of data allowance consumed
                  example: 80
                dataUsageBytes:
                  type: number
                  description: The amount of data consumed in bytes
                  example: 1231230
                esim:
                  type: string
                  description: The eSIM identifier
                  example: '8937103400004164763'
                planId:
                  type: string
                  description: The plan identifier
                  example: 33de44b0-5103-45ea-9723-0a7aa104c76a
                attachmentId:
                  type: string
                  description: The attachment identifier
                  example: a1ac5a45-e05b-4728-9253-17c54fc1c5ff
    LocationChangedEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            type:
              type: string
              default: subscription.esim.locationChanged
              example: subscription.esim.locationChanged
            data:
              type: object
              required:
                - esim
                - countryIso2
              properties:
                esim:
                  type: string
                  description: The eSIM identifier
                  example: '8937204017179541233'
                countryIso2:
                  type: string
                  description: The ISO 2-letter country code
                  example: IT
    SMDPInfo:
      type: object
      required:
        - iccid
        - state_history
      properties:
        iccid:
          type: string
          description: The ICCID of the SIM
          example: '8937103400004164763'
        state_history:
          type: array
          description: History of state changes for the eSIM profile
          items:
            type: object
            properties:
              state:
                type: string
                description: The state of the eSIM profile
                enum:
                  - BPP Installation
                  - Enable
                  - Disable
                  - Delete
                example: Enable
              modification_result:
                type: string
                description: Result of the state modification
                example: SUCCESS
              modified_at:
                type: string
                format: date-time
                description: Timestamp when the state was modified
                example: '2025-10-28T20:23:59.000Z'
        current_status:
          type: string
          description: Current status of the eSIM profile
          enum:
            - BPP Installation
            - Enable
            - Disable
            - Delete
          example: Enable
    SMDPInfoResponse:
      type: object
      properties:
        error:
          type: boolean
          example: false
        data:
          $ref: '#/components/schemas/SMDPInfo'
    Operator:
      type: object
      properties:
        operator_id:
          type: string
          description: The unique identifier for the operator
          example: 2dea792a-2dea-492c-815d-8fb826be8d49
        name:
          type: string
          description: The name of the operator
          example: AT&T USA
        iso2:
          type: string
          description: ISO 2-letter country code
          example: US
        supported_rats:
          type: array
          description: List of supported Radio Access Technologies (RATs)
          items:
            type: string
          example:
            - 4G
            - 5G
        mcc_mnc:
          type: array
          description: List of MCC-MNC codes associated with the operator
          items:
            type: string
          example:
            - 310-680
            - 310-410
      required:
        - operator_id
        - name
        - iso2
        - supported_rats
        - mcc_mnc
    OperatorListResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates if there was an error in the request
          example: false
        data:
          type: array
          description: An array of operator objects returned by the request
          items:
            $ref: '#/components/schemas/Operator'
      required:
        - error
        - data
    OperatorDetailResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: false
        data:
          $ref: '#/components/schemas/Operator'
      required:
        - error
        - data
    CustomRegionCoverageProfileResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: false
        data:
          type: object
          properties:
            coverage_id:
              type: string
              description: The unique identifier for the coverage profile
              example: 85089a51-801c-4737-bd8b-f542705712bf
            region_code:
              type: string
              description: The generated region code for the custom region
              example: R33BHT
            region_name:
              type: string
              description: The name of the custom region
              example: Usa and Mexico Regional Plan
            iso2_list:
              type: array
              description: List of ISO 2-letter country codes included in the custom region
              items:
                type: string
              example:
                - US
                - MX
          required:
            - coverage_id
            - region_code
            - region_name
            - iso2_list
      required:
        - error
        - data
    ListCoverageProfile:
      type: object
      properties:
        error:
          type: boolean
          example: false
        data:
          type: array
          items:
            $ref: '#/components/schemas/CoverageProfile'
      required:
        - error
        - data
    CoverageProfileDetailResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred during the request
          example: false
        data:
          $ref: '#/components/schemas/CoverageProfile'
      required:
        - error
        - data
    Label:
      type: string
      enum:
        - Green
        - Aqua
        - Blue
        - Voilet
        - Red
        - Grey
        - Orange
    SIMDetailResponse:
      type: object
      properties:
        error:
          type: boolean
        data:
          $ref: '#/components/schemas/ESIM'
    ThrottlingThresholdLimit:
      type: string
      example: '3072'
      description: >-
        Limit to apply when the subscriber is crossing the first threshold. It's
        units is Kbit/sec. Required if throttling is true.
      enum:
        - '128'
        - '256'
        - '384'
        - '512'
        - '1024'
        - '3072'
        - '5120'
        - '7680'
        - '10240'
        - '20480'
    ThrottlingThresholdSecondLimit:
      type: string
      example: '3072'
      description: >-
        Limit to apply when the subscriber is crossing the second threshold.
        It's units is Kbit/sec. Required if throttling_threshold2_perc is
        present in request.
      enum:
        - '128'
        - '256'
        - '384'
        - '512'
        - '1024'
        - '3072'
        - '5120'
        - '7680'
        - '10240'
        - '20480'
    ThrottlingThresholdThirdLimit:
      type: string
      example: '3072'
      description: >-
        Limit to apply when the subscriber is crossing the third threshold. It's
        units is Kbit/sec. Required if throttling_threshold3_perc is present in
        request.
      enum:
        - '128'
        - '256'
        - '384'
        - '512'
        - '1024'
        - '3072'
        - '5120'
        - '7680'
        - '10240'
        - '20480'
    PlanDeleteSuccessResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates if an error occurred.
          example: false
        message:
          type: string
          description: A message indicating the result of the operation.
          example: Plan deleted successfully
    UnauthorizedDeleteResponse:
      type: object
      properties:
        error:
          type: boolean
          description: A boolean indicating whether there was an error in the request
          example: true
        message:
          type: string
          description: A message indicating the reason for the unauthorized delete response
          example: Cannot delete a subscription whose esim was installed on a device
      required:
        - error
        - message
    UnArchiveResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether there was an error processing the request
          example: false
        message:
          type: string
          description: A message providing additional information about the request status
          example: Plan unarchived successfully
      required:
        - error
        - message
    NoAvailableESIMResponse:
      type: object
      properties:
        error:
          type: boolean
          example: true
        message:
          type: string
          example: No available eSIM record found for the specified plan label
      required:
        - error
        - message
    PlanAttachment:
      type: object
      properties:
        plan_attachment_id:
          type: string
          format: uuid
          example: ba3b527f-4a01-42e2-892a-fff6d217217e
        created_at:
          type: string
          format: date-time
          example: '2025-08-30T08:00:18.681Z'
        activation_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2025-08-30T08:00:18.681Z'
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2025-08-30T08:00:18.681Z'
        used_allowance:
          type: object
          properties:
            dataBytes:
              type: number
              example: 100
        state:
          type: string
          example: CREATED
        plan:
          type: object
          properties:
            name:
              type: string
              example: Usa plan green 1gb 7 days
            _id:
              type: string
              format: uuid
              example: e90b8df8-fc8a-4010-8d70-13c756017747
            coverage_id:
              type: string
              format: uuid
              example: 24648a7f-8281-4af7-8fc0-19b2371b2d1d
            region_code:
              type: string
              example: US
            label:
              type: string
              example: Green
            throttling:
              type: boolean
              example: false
            recurring:
              type: boolean
              example: false
            data_mega_bytes:
              type: integer
              example: 1024
            period_days:
              type: integer
              example: 7
    SendSMSBadGatewayResponse:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates whether an error occurred (true if an error occurred)
          example: true
        message:
          type: string
          description: >-
            A message providing additional information about the failure
            response
          example: SMS Delivery Failed
      required:
        - error
        - message
servers:
  - url: https://api.tellisim.com
    description: Production server
tags:
  - name: Subscriptions
    description: Operations related to subscriptions.
  - name: Plans
    description: Operations related to plans.
  - name: Coverage
    description: Operations related to coverage.
  - name: SIM
    description: Operations related to SIM management.
  - name: Operators
    description: Operations related to operators.
  - name: Webhook Events
    description: >
      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.
paths:
  /v3/coverage-profiles:
    get:
      tags:
        - Coverage
      summary: List coverage profiles
      description: Returns the list of coverage profiles available to your account.
      operationId: xwappasg4mnsd-list-coverage-profiles
      parameters:
        - name: region_code
          in: query
          required: false
          schema:
            type: string
          example: US
        - name: label
          in: query
          required: false
          schema:
            type: string
          example: Green
      responses:
        '200':
          description: Successful response containing coverage profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCoverageProfile'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/coverage-profiles/{coverageId}:
    get:
      tags:
        - Coverage
      summary: Get the coverage profile
      description: Retrieves the coverage profile
      operationId: fltojr54olllm-get-the-coverage-profile
      parameters:
        - name: coverageId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing coverage profile details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageProfileDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/coverage-profiles/custom-region:
    post:
      tags:
        - Coverage
      summary: Create custom region coverage profile
      description: >
        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.
      operationId: 9dtoar54odjsm-create-custom-region-coverage-profile
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - region_name
                - label
                - iso2_list
              properties:
                region_name:
                  type: string
                  description: The name of the custom region.
                  example: Usa and Mexico Regional Plan
                label:
                  $ref: '#/components/schemas/Label'
                iso2_list:
                  type: array
                  description: >-
                    List of ISO 2-letter country codes included in the custom
                    region.
                  items:
                    type: string
                  example:
                    - US
                    - MX
            examples:
              default:
                summary: Example custom region request
                value:
                  region_name: Usa and Mexico Regional Plan
                  label: Green
                  iso2_list:
                    - US
                    - MX
      responses:
        '200':
          description: >-
            Successful response containing the created custom region coverage
            profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRegionCoverageProfileResponse'
              examples:
                success:
                  summary: Successful custom region creation
                  value:
                    error: false
                    data:
                      coverage_id: 85089a51-801c-4737-bd8b-f542705712bf
                      region_code: R33BHT
                      region_name: Usa and Mexico Regional Plan
                      iso2_list:
                        - US
                        - MX
        '400':
          description: >-
            Bad request - either a custom region with this name already exists
            for this organization, or one or more provided ISO2 country codes
            have no operators assigned.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                properties:
                  error:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: >-
                      Custom region with this name already exists for this
                      organization
                  missing_iso2:
                    type: array
                    description: >-
                      List of ISO2 country codes from the request for which no
                      operators were found.
                    items:
                      type: string
              examples:
                nameAlreadyExists:
                  summary: Custom region name already exists
                  value:
                    error: true
                    message: >-
                      Custom region with this name already exists for this
                      organization
                missingOperatorsForIso2:
                  summary: No operators found for one or more provided ISO2 codes
                  value:
                    error: true
                    message: No operators found for one or more provided iso2 codes
                    missing_iso2:
                      - UK
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '409':
          description: >-
            Conflict - a coverage profile with the exact same set of countries
            already exists. The existing coverage coverage details are returned.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                  - existing_coverage
                properties:
                  error:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Coverage id with same operator already exists
                  existing_coverage:
                    type: object
                    required:
                      - coverage_id
                      - region_code
                      - region_name
                      - iso2_list
                    properties:
                      coverage_id:
                        type: string
                        example: 85089a51-801c-4737-bd8b-f542705712bf
                      region_code:
                        type: string
                        example: R33BHT
                      region_name:
                        type: string
                        example: TEST USA and Mexico
                      iso2_list:
                        type: array
                        items:
                          type: string
                        example:
                          - US
                          - MX
              examples:
                coverageConflict:
                  summary: Coverage with same operator already exists
                  value:
                    error: true
                    message: Coverage id with same operator already exists
                    existing_coverage:
                      coverage_id: 85089a51-801c-4737-bd8b-f542705712bf
                      region_code: R33BHT
                      region_name: TEST USA and Mexico
                      iso2_list:
                        - US
                        - MX
  /v3/sims:
    get:
      tags:
        - SIM
      summary: List SIMs
      description: >-
        This endpoint retrieves a list of SIMs(both eSIMs and physical sim
        cards) associated with organization.
      operationId: s3rz0wvzvnuuz-list-sims
      parameters:
        - name: page_size
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: string
        - name: is_esim
          in: query
          schema:
            type: boolean
        - name: label
          in: query
          required: false
          schema:
            type: string
          example: Green
      responses:
        '200':
          description: Successful response containing a list of SIMs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESIMListResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/sims/{iccid}:
    get:
      tags:
        - SIM
      summary: Get SIM details
      description: This endpoint retrieves the details of a specific SIM by its ICCID.
      operationId: xou0n7wvmb58j-get-sim-by-iccid
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing the SIM details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SIMDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/sims/{iccid}/smdp-info:
    get:
      tags:
        - SIM
      summary: Get SIM SMDP information
      description: >
        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
      operationId: ftvathnftu1cu-get-sim-smdp-info
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
          description: The ICCID of the SIM
      responses:
        '200':
          description: Successful response containing the SMDP information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMDPInfoResponse'
              example:
                error: false
                data:
                  iccid: '8948010000031326267'
                  state_history:
                    - state: Enable
                      modification_result: SUCCESS
                      modified_at: '2025-10-28T20:23:59.000Z'
                    - state: BPP Installation
                      modification_result: SUCCESS
                      modified_at: '2025-10-28T20:23:51.000Z'
                  current_status: Enable
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/plans:
    get:
      tags:
        - Plans
      summary: List plans
      description: >-
        This endpoint retrieves a list of available plans. It allows users to
        specify pagination and filter out archived plans.
      operationId: roe63e3fhdeh5-list-plans
      parameters:
        - name: archived
          in: query
          schema:
            type: boolean
          description: >-
            When true, only archived plans are returned. When false, only non
            archived plans are returned. When absent all are returned.
        - name: page_size
          in: query
          description: Number of items to be returned in a single page
          schema:
            type: string
            minimum: 1
            maximum: 25
            default: 10
        - name: page
          in: query
          description: >-
            A cursor for pagination across multiple pages of results. Don’t
            include this parameter on the first call.
          schema:
            type: string
        - name: label
          in: query
          description: >-
            Filter plans by label. Allowed values are Green, Aqua, Blue, Voilet,
            Red, Grey, Orange
          schema:
            $ref: '#/components/schemas/Label'
        - name: search_query
          in: query
          description: Query to search the plans by name
          schema:
            type: string
        - name: country_iso_2
          in: query
          description: Comma separated list of countryIso2 e.g. countryIso2=FR,IN
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful response containing a list of plans. The optional fields
            are returned for labels on which throttling or recurring is enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanListResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    post:
      tags:
        - Plans
      summary: Create Plans
      description: Creates a plan with the given configuration.
      operationId: rsq2cu2wtponb-create-plans
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - coverage_id
                - data_MBs
                - name
                - recurring
                - throttling
                - period_days
              properties:
                coverage_id:
                  type: string
                  example: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
                  description: coverage id of the region.
                data_MBs:
                  type: number
                  example: 1024
                  description: The amount of MBs you want in the plan
                  minimum: 1
                name:
                  type: string
                  example: test1 recurring and throttling package
                  description: Name of the plan which can be any thing you like.
                period_days:
                  type: number
                  example: 1
                  minimum: 1
                  maximum: 1825
                  description: plan validity in days
                recurring:
                  type: boolean
                  example: true
                  description: Set to true if you want the plan to be recurring
                throttling:
                  type: boolean
                  example: true
                  description: Set to true if you want the plan to be throttled
                nb_occurrence:
                  type: number
                  example: 2
                  description: >-
                    The number of occurrences for the plan. Required if
                    recurring is true.
                  minimum: 2
                  maximum: 550
                recurring_periodicity_type:
                  type: string
                  example: '0'
                  enum:
                    - '0'
                    - '1'
                    - '2'
                  description: >-
                    Recurring periodicity type. Possible values are 0=Daily,
                    1=Weekly, 2=Monthly. Required if recurring is true.
                recurring_periodicity_frequency:
                  type: number
                  example: 2
                  description: >-
                    Along with recurring_periodicity_type will determine the
                    frequency at which the subscriber will receive its packages.
                    For example recurring_periodicity_frequency=0 and
                    recurring_periodicity_frequency=2, the subscriber is going
                    to receive a package every 2 days. Required if recurring is
                    true.
                throttling_threshold1_perc:
                  type: number
                  example: 50
                  minimum: 0
                  maximum: 100
                  description: >-
                    First threshold for throttling, in percentage of the total
                    volume of the package. Required if throttling is true.
                throttling_threshold1_limit:
                  $ref: '#/components/schemas/ThrottlingThresholdLimit'
                throttling_threshold2_perc:
                  type: number
                  example: 90
                  minimum: 0
                  maximum: 100
                  description: >-
                    Second threshold for throttling, in percentage of the total
                    volume of the package. Required if throttling is true.
                throttling_threshold2_limit:
                  $ref: '#/components/schemas/ThrottlingThresholdSecondLimit'
                throttling_threshold3_perc:
                  type: number
                  example: 100
                  minimum: 0
                  maximum: 100
                  description: >-
                    Third threshold for throttling, in percentage of the total
                    volume of the package. Required if throttling is true.
                throttling_threshold3_limit:
                  $ref: '#/components/schemas/ThrottlingThresholdThirdLimit'
            examples:
              default:
                summary: With recurring and throttling enabled
                value:
                  coverage_id: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
                  data_MBs: 1024
                  name: test1 recurring and throttling package
                  period_days: 1
                  recurring: true
                  throttling: true
                  nb_occurrence: 2
                  recurring_periodicity_type: '0'
                  recurring_periodicity_frequency: 2
                  throttling_threshold1_perc: 50
                  throttling_threshold1_limit: '1024'
                  throttling_threshold2_perc: 90
                  throttling_threshold2_limit: '1024'
                  throttling_threshold3_perc: 100
                  throttling_threshold3_limit: '1024'
              minimal:
                summary: Minimal example with recurring and throttling disabled
                value:
                  coverage_id: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
                  data_MBs: 1024
                  name: minimal package
                  period_days: 1
                  recurring: false
                  throttling: false
              throttling_only:
                summary: With only throttling enabled
                value:
                  coverage_id: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
                  data_MBs: 1024
                  name: throttling only package
                  period_days: 1
                  recurring: false
                  throttling: true
                  throttling_threshold1_perc: 50
                  throttling_threshold1_limit: '1024'
                  throttling_threshold2_perc: 90
                  throttling_threshold2_limit: '1024'
                  throttling_threshold3_perc: 100
                  throttling_threshold3_limit: '1024'
              recurring_only:
                summary: With only recurring enabled
                value:
                  coverage_id: 819b05c4-f154-4df9-8fd1-16be3e82f5c6
                  data_MBs: 1024
                  name: recurring only package
                  period_days: 1
                  recurring: true
                  throttling: false
                  nb_occurrence: 2
                  recurring_periodicity_type: '0'
                  recurring_periodicity_frequency: 2
      responses:
        '201':
          description: Plan created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCreateResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
      x-codegen-request-body-name: body
  /v3/plans/{planId}:
    get:
      tags:
        - Plans
      summary: Get a Plan
      description: Retrieves the details of an existing plan by its ID.
      operationId: 8p6b2qv85fzoj-get-a-plan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    delete:
      tags:
        - Plans
      summary: Delete a Plan
      description: >-
        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.
      operationId: delete-a-plan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The plan was deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanDeleteSuccessResponse'
        '401':
          description: Unauthorized request due to missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDeleteResponse'
  /v3/plans/{planId}/archive:
    post:
      tags:
        - Plans
      summary: Archive a plan
      description: >-
        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.
      operationId: 2vx77nutyy4a1-archive-a-plan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plan archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/plans/{planId}/unarchive:
    post:
      tags:
        - Plans
      summary: Unarchive a plan
      description: >-
        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.
      operationId: 3pax3wmtx0ckv-unarchive-a-plan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plan unarchived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnArchiveResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/subscription:
    get:
      tags:
        - Subscriptions
      summary: List Subscriptions
      description: >
        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.
      operationId: kuy01agj9wxkq-list-subscriptions
      responses:
        '200':
          description: Successful response containing subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    post:
      tags:
        - Subscriptions
      summary: Create Subscriptions
      description: >
        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.
      operationId: y0553xy7w914c-create-subscriptions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - plan_id
                - metadata
              properties:
                iccid:
                  type: string
                  example: '8948010000031324502'
                  description: >
                    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.
                metadata:
                  type: string
                  example: usa recurring plan
                plan_id:
                  type: string
                  example: 0a3ee1d6-fe5e-4561-91a0-d4649aaf0754
                active_period:
                  type:
                    - object
                    - 'null'
                  description: >
                    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.
                  properties:
                    start:
                      type: string
                      format: date-time
                      description: |
                        Desired activation start time (ISO 8601, UTC).
                        - **Non‑recurring plans**: required when `active_period`
                          is provided and must be sent together with `end`.
                        - **Recurring plans**: required when `active_period` is
                          provided. You may send only `start` without `end`.
                      example: '2025-12-10T15:03:28.533603'
                    end:
                      type:
                        - string
                        - 'null'
                      format: date-time
                      description: >
                        Desired expiration time (ISO 8601, UTC).

                        - **Non‑recurring plans**: required when `active_period`
                          is provided.
                        - **Recurring plans**: optional. If omitted, the
                        recurring
                          package uses the plan’s configured validity and default
                          activation behavior.
                      example: '2025-12-20T15:03:28.533603'
      responses:
        '201':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCreateResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '404':
          description: No available eSIM found for the specified plan label
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoAvailableESIMResponse'
      x-codegen-request-body-name: body
  /v3/subscriptions/{iccid}:
    get:
      tags:
        - Subscriptions
      summary: Get a subscription
      description: >-
        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.
      operationId: 9r03ycqqjdxez-get-a-subscription
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
    delete:
      tags:
        - Subscriptions
      summary: Delete a Subscription
      description: >-
        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.
      operationId: r5cdqtky0qde0-delete-a-subscription
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscription deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '403':
          description: >-
            The subscription cannot be deleted because the esim profile
            associated with the ICCID was already downloaded by an end-user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedDeleteResponse'
  /v3/subscriptions/{iccid}/plan-attachments:
    get:
      tags:
        - Subscriptions
      summary: List plan attachments
      description: >-
        This endpoint retrieves the plan attachments associated with a specific
        subscription identified by its ICCID.
      operationId: urh0yrd5tx486-list-plan-attachments
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing plan attachments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAttachmentListResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/subscriptions/{iccid}/plan-attachments/{plan_id}:
    get:
      tags:
        - Subscriptions
      summary: Get a plan attachment
      description: >-
        This endpoint retrieves the details of a specific plan attachment for a
        subscription.
      operationId: get-plan-attachment-by-id
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
        - name: plan_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing the plan attachment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAttachmentDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/subscriptions/{iccid}/plan-attachments/{id}/suspend:
    post:
      tags:
        - Subscriptions
      summary: Suspend a plan attachment
      description: >-
        This operation stops all telco services on this attachment and puts it
        in a suspended state. This is a non-reversible operation.
      operationId: 7vircgwk1k8dm-suspend-a-plan-attachment
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plan attachment suspended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspendResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/subscriptions/{iccid}/send-sms:
    post:
      tags:
        - Subscriptions
      summary: Send sms
      description: >-
        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.
      operationId: 8znze4vr6c4v9-send-sms
      parameters:
        - name: iccid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - message
              properties:
                from:
                  type: string
                  example: tellisim
                message:
                  type: string
                  example: test message
      responses:
        '200':
          description: SMS sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMSResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '502':
          description: Bad Gateway - Error sending SMS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSMSBadGatewayResponse'
      x-codegen-request-body-name: body
  /v3/operators:
    get:
      tags:
        - Operators
      summary: List operators
      description: >-
        Returns the list of operators filtered by optional label and country
        filters.
      operationId: u8ed9w0ej2nj4-list-operators
      parameters:
        - name: label
          in: query
          required: false
          description: >-
            Filter operators by label. Allowed values are Green, Aqua, Blue,
            Voilet, Red, Grey, Orange.
          schema:
            $ref: '#/components/schemas/Label'
        - name: iso2_codes
          in: query
          required: false
          description: >-
            Comma separated list of ISO 2-letter country codes. For example:
            iso2_codes=MX,US
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing a list of operators.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorListResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
  /v3/operators/{operatorId}:
    get:
      tags:
        - Operators
      summary: Get operator
      description: Retrieves the details of a specific operator.
      operationId: 9ej4esdkfjfe9-get-operator
      parameters:
        - name: operatorId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing operator details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatorDetailResponse'
        '401':
          description: Unauthorized - API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
webhooks:
  attachment.allowanceConsumed:
    post:
      summary: Data allowance consumed
      description: |
        Triggered when 50%, 80%, or 100% of a fixed validity plan's 
        data allowance is consumed (no events for recurring plans).
      operationId: attachment-allowance-consumed
      tags:
        - Webhook Events
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - timestamp
                - data
              properties:
                type:
                  type: string
                  example: attachment.allowanceConsumed
                timestamp:
                  type: integer
                  description: Unix timestamp when the event was fired
                  example: 1730474606
                data:
                  type: object
                  required:
                    - usagePercentage
                    - dataUsageBytes
                    - esim
                    - planId
                    - attachmentId
                  properties:
                    usagePercentage:
                      type: number
                      minimum: 0
                      maximum: 100
                      description: Percentage of data allowance consumed
                      example: 80
                    dataUsageBytes:
                      type: number
                      description: Data consumed in bytes
                      example: 1231230
                    esim:
                      type: string
                      description: The eSIM or physical SIM identifier
                      example: '8937103400004164763'
                    planId:
                      type: string
                      description: The plan identifier
                      example: 33de44b0-5103-45ea-9723-0a7aa104c76a
                    attachmentId:
                      type: string
                      description: The attachment identifier
                      example: a1ac5a45-e05b-4728-9253-17c54fc1c5ff
            example:
              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:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
  subscription.esim.locationChanged:
    post:
      summary: SIM location changed
      description: |
        Triggered when a SIM's country location changes.
      operationId: subscription-esim-location-changed
      tags:
        - Webhook Events
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - timestamp
                - data
              properties:
                type:
                  type: string
                  example: subscription.esim.locationChanged
                timestamp:
                  type: integer
                  description: Unix timestamp when the event was fired
                  example: 1759429928
                data:
                  type: object
                  required:
                    - esim
                    - countryIso2
                  properties:
                    esim:
                      type: string
                      description: The eSIM or physical SIM identifier
                      example: '8937204017179541233'
                    countryIso2:
                      type: string
                      description: ISO 2-letter country code
                      example: IT
            example:
              type: subscription.esim.locationChanged
              timestamp: 1759429928
              data:
                esim: '8937204017179541233'
                countryIso2: IT
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
  esim.smdp.stateChanged:
    post:
      summary: SIM SMDP Status Changed
      description: |
        The event is sent whenever the SMDP state of an event is changed.
      operationId: esim-smdp-state-changed
      tags:
        - Webhook Events
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - timestamp
                - data
              properties:
                type:
                  type: string
                  example: esim.smdp.stateChanged
                timestamp:
                  type: integer
                  description: Unix timestamp when the event was fired
                  example: 1761991449
                data:
                  type: object
                  required:
                    - sim
                    - smdpStateChange
                  properties:
                    sim:
                      type: string
                      description: The eSIM or physical SIM identifier
                      example: '8937204017179541233'
                    smdpStateChange:
                      type: object
                      required:
                        - state
                        - modificationResult
                      properties:
                        state:
                          type: string
                          description: The SMDP state
                          enum:
                            - BPP Installation
                            - Enable
                            - Disable
                            - Delete
                          example: Enable
                        modificationResult:
                          type: string
                          description: The result of the state modification
                          example: SUCCESS
            example:
              type: esim.smdp.stateChanged
              timestamp: 1761991449
              data:
                sim: '8937204017179541233'
                smdpStateChange:
                  state: Enable
                  modificationResult: SUCCESS
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
x-original-swagger-version: '2.0'
