openapi: 3.0.1
info:
  title: Maya Mobile Connect+ Connectivity eSIMs API
  description: 'Maya Mobile (Mobile Maya Inc) Connect+ Connectivity REST API for provisioning eSIMs and data packages, monitoring activation status and data usage, processing top-ups, and receiving lifecycle events via webhooks across 400+ roaming networks in 200+ destinations.


    NOTE: Maya Mobile distributes the full Connectivity API reference under NDA to onboarded resellers and partners. This document models the publicly described capabilities of the Connect+ API (eSIM provisioning, data packages/plans, status and usage, top-ups, orders, and webhooks). Exact endpoint paths, request/response schemas, and authentication parameters are confirmed against the partner documentation during onboarding and are not fully published. Paths below reflect the documented capability surface and are marked as unreconciled where exact shapes are not public.'
  termsOfService: https://maya.net/terms
  contact:
    name: Maya Mobile Partnerships
    url: https://maya.net/business
  version: '1.0'
servers:
- url: https://api.maya.net/connectivity/v1
  description: Connect+ Connectivity API base URL (representative; confirm exact host and version path against partner documentation during onboarding).
security:
- bearerAuth: []
tags:
- name: eSIMs
  description: eSIM provisioning, activation codes/QR, suspend and reactivate.
paths:
  /esims:
    post:
      operationId: createEsim
      tags:
      - eSIMs
      summary: Provision a new eSIM
      description: Requests an eSIM with the selected roaming profile and returns the activation code and QR code ready to install.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEsimRequest'
      responses:
        '201':
          description: The provisioned eSIM with activation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}:
    get:
      operationId: getEsim
      tags:
      - eSIMs
      summary: Get an eSIM
      description: Returns the current state and installation status of a single eSIM.
      parameters:
      - name: esimId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested eSIM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}/suspend:
    post:
      operationId: suspendEsim
      tags:
      - eSIMs
      summary: Suspend an eSIM
      description: Suspends an active eSIM anywhere in the world.
      parameters:
      - name: esimId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The eSIM after suspension.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}/reactivate:
    post:
      operationId: reactivateEsim
      tags:
      - eSIMs
      summary: Reactivate an eSIM
      description: Reactivates a previously suspended eSIM.
      parameters:
      - name: esimId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The eSIM after reactivation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
components:
  schemas:
    Esim:
      type: object
      properties:
        id:
          type: string
        iccid:
          type: string
        status:
          type: string
          description: Lifecycle status (e.g. provisioned, installed, active, suspended).
        activation_code:
          type: string
          description: Manual activation code for the eSIM profile.
        qr_code_url:
          type: string
          description: URL of the QR code used to install the eSIM.
    CreateEsimRequest:
      type: object
      properties:
        plan_id:
          type: string
          description: Identifier of the plan/roaming profile to provision.
        region:
          type: string
        country:
          type: string
      required:
      - plan_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token / API key supplied in the Authorization header (`Authorization: Bearer <token>`). Credentials are issued to onboarded Maya Mobile resellers/partners.'