esimaccess-api

eSIM Access API Skill

Interact with the eSIM Access API for complete eSIM lifecycle management.

When to Use This Skill

Use this skill when the user:

• Asks about eSIM operations: ordering, top-ups, cancellations, status checks
• Mentions ICCID, order number, QR code, or data usage
• Wants to check account balance or list available data packages
• Asks about roaming, travel data plans, or mobile connectivity
• Needs to manage eSIM profiles (suspend, unsuspend, revoke)
• Wants to configure webhooks for eSIM status notifications
• Asks to cancel and reissue an eSIM (refund/replace workflow)
• References the eSIM Access API or api.esimaccess.com

Example prompts

• "Check my eSIM Access balance"
• "What packages are available for Japan?"
• "Order a 5GB plan for the US"
• "Check the status of order B26041021130002"
• "How much data has ICCID 89852240810733629810 used?"
• "Top up my eSIM with another 5GB"
• "Cancel this unused eSIM and get a refund"
• "Set up a webhook for order notifications"

Quick Reference

• Base URL: https://api.esimaccess.com/api/v1/open
• Auth: HMAC-SHA256 signed headers — the accessCode is used as both the API identifier and signing key (see references/api-reference.md)
• Prices: API values / 10,000 = USD (e.g., 18000 = $1.80)
• Volumes: Bytes (1073741824 = 1 GB)
• Credentials: Get your accessCode from https://console.esimaccess.com/developer/index

Operations

Read (safe)

| Operation | Endpoint | Purpose | |-----------|----------|---------| | check_balance | /balance/query | Account balance in USD | | list_regions | /package/list | All supported countries | | list_packages | /package/list | Products by country/code | | list_topup_packages | /package/list | Top-up options for ICCID | | check_order_status | /esim/query | Order details + ICCID | | check_esim_status | /esim/query | Full eSIM profile info | | check_data_usage | /esim/usage/query | Data consumption stats | | query_webhook | /webhook/query | Current webhook config |

Write (costs money or modifies state)

| Operation | Endpoint | Purpose | |-----------|----------|---------| | create_order | /esim/order | Purchase new eSIM | | apply_topup | /esim/topup | Add data to existing eSIM | | cancel_esim | /esim/cancel | Cancel unused eSIM (refund) | | suspend_profile | /esim/suspend | Temporarily disable | | unsuspend_profile | /esim/unsuspend | Re-enable suspended | | revoke_profile | /esim/revoke | Permanently disable (no refund) | | send_sms | /esim/sendSms | Send SMS to eSIM | | setup_webhook | /webhook/save | Configure notification URL |

Composite Workflows

| Operation | Purpose | |-----------|---------| | refund_and_reissue | Cancel unused eSIM, verify refund, order replacement with same package |

Key Rules

1. Order flow: create_order returns orderNo. Poll check_order_status every 3s (4 retries) for ICCID. ORDER_STATUS webhook is fallback.
2. Top-ups: Use esimTranNo (not ICCID). supportTopUpType === 2 means eligible. Cannot top up after expiry.
3. Cancel vs Revoke: Cancel works on unused eSIMs (RELEASED/GOT_RESOURCE) and provides refund. Revoke works on activated eSIMs with no refund.
4. Usage query: Requires esimTranNo, not ICCID. Do an ICCID lookup via /esim/query first if needed.
5. SMS: Uses message field (not content). Only works on activated eSIMs.

Authentication in Any Language

The references/api-reference.md file contains HMAC-SHA256 auth examples in both Node.js and Python. Ask your AI to generate auth code in your preferred language using the signature algorithm documented there.

Testing

node scripts/test-esim-api.mjs <accessCode>

Installation

Any AI agent (via Skills CLI)

npx skills add esimaccess/esimaccess-api

Manual install

Download from https://app.esimaccess.com/public/skill/ and place in your agent's skills directory.

Files

| File | Purpose | |------|---------| | SKILL.md | This file - skill definition | | scripts/test-esim-api.mjs | 15 end-to-end API tests | | references/api-reference.md | Full API docs: endpoints, auth, status states, webhooks, error codes |