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
- Order flow:
create_orderreturnsorderNo. Pollcheck_order_statusevery 3s (4 retries) for ICCID. ORDER_STATUS webhook is fallback. - Top-ups: Use
esimTranNo(not ICCID).supportTopUpType === 2means eligible. Cannot top up after expiry. - Cancel vs Revoke: Cancel works on unused eSIMs (RELEASED/GOT_RESOURCE) and provides refund. Revoke works on activated eSIMs with no refund.
- Usage query: Requires
esimTranNo, not ICCID. Do an ICCID lookup via/esim/queryfirst if needed. - SMS: Uses
messagefield (notcontent). 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 |