> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onroamly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an eSIM

> A single eSIM belonging to your account.



## OpenAPI

````yaml /openapi.yaml get /v1/esims/{esimId}
openapi: 3.0.3
info:
  title: Roamly API
  version: 1.0.0
  description: |
    Programmatic access to Roamly's travel eSIM plan catalog — every
    destination we sell, every plan, with live pricing.

    **Base URL:** `https://api.onroamly.com`

    All endpoints are read-only `GET` requests returning JSON, and require
    an API key sent as `Authorization: Bearer rk_live_…`. Keys are managed
    from your [Roamly account](https://www.onroamly.com/account/api).
  contact:
    name: Roamly
    email: hello@onroamly.com
    url: https://www.onroamly.com
servers:
  - url: https://api.onroamly.com
security:
  - bearerAuth: []
tags:
  - name: Destinations
    description: Countries and regional bundles Roamly sells plans for.
  - name: Plans
    description: The sellable plan catalog.
  - name: eSIMs
    description: >
      eSIMs purchased by your own account. Every key is tied to one Roamly
      account and returns only that account's eSIMs.
paths:
  /v1/esims/{esimId}:
    get:
      tags:
        - eSIMs
      summary: Get an eSIM
      description: A single eSIM belonging to your account.
      operationId: getEsim
      parameters:
        - name: esimId
          in: path
          required: true
          description: The eSIM `id` from `/v1/esims`.
          schema:
            type: string
      responses:
        '200':
          description: The eSIM.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Esim'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No eSIM with that id on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: esim_not_found
                  message: No eSIM with id 'abc'.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Esim:
      type: object
      properties:
        id:
          type: string
          example: 8Kd0kQ2mXpLz1vRb3nTy
        status:
          type: string
          description: >
            `paid` on purchase, `provisioning` while we issue it, `ready` once
            installable, then `expired` or `depleted` at end of life. `failed`
            means provisioning didn't complete.
          enum:
            - paid
            - provisioning
            - ready
            - failed
            - expired
            - depleted
        plan:
          type: object
          properties:
            name:
              type: string
              example: Japan 5GB 30 days
            destination:
              type: object
              properties:
                code:
                  type: string
                  example: JP
                name:
                  type: string
                  example: Japan
                type:
                  type: string
                  enum:
                    - country
                    - region
            dataAmountGB:
              type: number
              nullable: true
              example: 5
            dataType:
              type: string
              enum:
                - total
                - daily
            validityDays:
              type: integer
              nullable: true
              example: 30
            speed:
              type: string
              nullable: true
              example: 4G/5G
        esim:
          type: object
          description: Installation details. Populated once `status` is `ready`.
          properties:
            iccid:
              type: string
              nullable: true
            activationCode:
              type: string
              nullable: true
              description: The LPA string, for manual installation.
            qrCodeUrl:
              type: string
              nullable: true
            iosInstallUrl:
              type: string
              nullable: true
              description: One-tap universal link that opens iOS eSIM setup.
            androidInstallUrl:
              type: string
              nullable: true
            apn:
              type: string
              nullable: true
            pin:
              type: string
              nullable: true
            puk:
              type: string
              nullable: true
        usage:
          type: object
          description: Latest reading from our hourly poll — `updatedAt` says how fresh.
          properties:
            usedMB:
              type: number
              nullable: true
            remainingMB:
              type: number
              nullable: true
            totalMB:
              type: number
              nullable: true
            updatedAt:
              type: string
              format: date-time
              nullable: true
        price:
          $ref: '#/components/schemas/Money'
        purchasedAt:
          type: string
          format: date-time
          nullable: true
        fulfilledAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: not_found
            message:
              type: string
              example: Unknown route.
    Money:
      type: object
      properties:
        amount:
          type: number
          format: float
          example: 14.5
        currency:
          type: string
          enum:
            - AUD
            - USD
          example: AUD
  responses:
    Unauthorized:
      description: Missing, malformed, unknown, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: missing_api_key
              message: 'Provide your API key as ''Authorization: Bearer rk_live_…''.'
    RateLimited:
      description: Rate limit exceeded (120 requests/minute per key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded (120 requests/minute per key).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Roamly API key, e.g. `Authorization: Bearer rk_live_…`'

````