Deliver eSIM data plan packages via the eSIM Access HTTP API. Step by step overview.
\nCreate an account at eSIM Access
\nDeposit funds for testing and refunding
\nAdd your AccessCode below and run in your terminal or powershell to make your first API call
\ncurl --location --request POST 'https://api.esimaccess.com/api/v1/open/balance/query' \n--header 'RT-AccessCode: YOUR_ACCCESS_CODE' \n--data ''\n\ncurl -Uri \"https://api.esimaccess.com/api/v1/open/balance/query\" `\n -Method POST `\n -Headers @{\"RT-AccessCode\"=\"YOUR_ACCESS_CODE\"} `\n -Body \"\"\n\nVersion 1 - OCT 11, 2022 - Initial Release
\nVersion 1.1 - JUN 6, 2023 - Updates:
\nSingle Profile ordering changed to batch Profile ordering [via Order Profiles request]
\nOffline post-paying changed to online pre-paying [via Order Profiles request]
\nesim/list endpoint removed, status function found in esim/query
\nCancel, Suspend, Unsuspend and Revoke functions added
\nCountry filter added to Query All Data Packages
\nWebook for order status checking added
\nVersion 1.2 - JUL 26, 2023 - Updates:
\nAdded Top Up endpoint for adding data to existing eSIM profiles
\nQuery available Top Up plans with iccid or packageCode
Price and amount optional when ordering a profile
Version 1.3 - DEC 12, 2023 - Updates:
\nAdds slug as an alias to package code
Adds additional package data like speed, network, and favorite
Version 1.4 Mar 12, 2024 - Updates:
\nAdd SMS send to iccid ability
Adds ability to write webhooks
\nVersion 1.5 July 28, 2024 - Updates:
\nAdds daypass plans with periodNum parameter in Order Profiles
Adds rate limit of 8 requests per second
\nVersion 1.6 Dec 20, 2024 - Updates:
\nsupportTopUpType and ipExportUpdate Mar 8, 2025
\nAdds additional webhook for low balance now at 25% and 10% remaining
\nAdds balance check endpoint with last updated date
\nUpdate Mar 19, 2025
\nUpdate May 28, 2025
\nSMDP_EVENT which give SM-DP+ server eventsUpdate July 24, 2025
\nUpdate Dec 2, 2025
\ndatatype search fuppolicy result when viewing data packages.Update Apr 1, 2026
\nThere is no Sandbox environment. Cancel eSIM orders as needed in our live environment. Request funds for testing.
\nhttps://api.esimaccess.com
Image assets:
\nhttps://p.qrsim.net/
Requst your API keys in your online account.
\nTime codes are presented in UTC. Country codes use Alpha-2 ISO. Data values are in Bytes.
\nServer status tracked via postman monitors.
\n8 API request per second are allowed.
\nRequest a list of all the available data packages offered. Optionally filter by country or region.
\nAdditionaly request all of the Top Up plans available for a specific packageCode , slug or ICCID. Specific top ups work with specific plans. In general, countries can be reloaded with same country top up and region with same region top up.
Order profiles individualy or in batch. After successful ordering, the SM-DP+ server will return the OrderNo and allocate profiles asynchronously for the order.
Provide a uniqe transactionId for each order. Duplicate transactionId will be identified as the same request.
Provide the packageCode or slug of the data package(s) you will order.
Provide the count for each package needed.
Optional price check: Provide the price and multiply with count for the total cost to provide the amount.
Optional period: For daily plans include the periodNum corresponding to the number of days of the plan.
A successful order will generate an orderNo. Query all the allocated profiles in the endpoint /api/v1/open/esim/query
Query all eSIM profiles for both new eSIMs, and in use eSIMs.
\nQuery by orderNo or startTime and endTime range with paging options.
Use orderNo to request newly orderd eSIM profiles. The response will return the eSIM payload after all the allocated profiles are asynchronously allocated by the server. Expect wait times of up to 30 seconds. You can order up to 30 eSIMs in one batch and all profiles will be returnd with orderNo results.
If the profiles are not yet ready for download, the error will be returned (error code will be 200010, meaning SM-DP+ is still allocating profiles for the order).
Use the webhook notification \"notifyType\":\"ORDER_STATUS\" to inform your first get eSIM request. ORDER_STATUS webhook will trigger when the eSIM profiles have been created and ready for retrival.
Use esimTranNo , orderNo , or iccid to request the status of an eSIM including it's current orderUsage and eSIMStatus. Or use startTime and endTime range. esimTranNo and iccid will return a single eSIM, while orderNo will return the batch order of eSIMs.
Important Note: The value of orderUsage is updated within 2-3 hours after eSIM is in use.
Note: iccids are resued, thus the suggested method of eSIM status check is via esimTranNo.
Note: Rate limiting limits to 8 requests per second.
\nResults of several paramaters can identify the current state of any eSIM profile. For example:
\nCancel an inactive, unused eSIM profile.
The eSIM price is refunded to your balance.
This operation is available when esimStatus is GOT_RESOURCE and smdpStatus is RELEASED meaning the eSIM was created, but not installed on a device.
Cancel endpoint not available once user has used data with the eSIM.
\nIt is reccomended to use the esimTranNo when making a cancel request.
Use the Cancel Profile endpoint to make refunds, test eSIM purchases and return the value of unused eSIM to your account balance.
\nRequest to suspend or pause data service to an esim profile.
\nRequest to unsuspend or reactivate data service to an esim profile.
\nRequest to close and remove an active eSIM and data plan. Non-refundable.
\nQuery the balance of a merchant account. Balance is used when ordering data profiles.
None.
\nBefore making a top up, it is reccomended to query the available top up plans (Get All Data Packages endpoint) for a specific iccid , esimTranNoor packageCode first. This will give you available top up packages specific to this eSIM. Also supportTopUpType 2 or 3 means that plan suports top up. Learn more about top ups.
The top up endpoint allows an existing installed eSIM to be loaded with a new plan. To top up the plan, you need its ICCID or esimTranNo and the compatible top up data plan packageCode. and periodNum in case of Day Pass extensions.
Top ups can be requested while the eSIM is in New, In Use or Depleted status, but not after eSIM expiry.
\nRespone Parameters
\n","auth":{"type":"apikey","apikey":{"value":"{{accessCode}}","key":"Set or update your webhook URL via an API call. You can find the result in your console account here.
\nYou can also view the currently set webhook with the following endpoint:/api/v1/open/webhook/query
This endpoint is used to send SMS to an eSIM via iccid or esimTranNo. Supported by some networks. Only installed eSIMs that supports receiving SMS will work.
The smsStatus parameter in the /order and /package endpoints indicates whether the eSIM supports receiving SMS ( \"smsStatus\": 1 or 2) . There is currently no cost for SMS delivery.
Check the data usage of up to 10 eSIMs via their esimTranNo. Returns the amout of dataUsage, the totalData in the plan, and the lastUpdateTime timestamp of the most recent data used value update.
Important Note: Data usage is updated every 2-3 hours and is not real time.
\n","auth":{"type":"apikey","apikey":{"value":"{{accessCode}}","key":"Check our currently supported countries and plan codes.
\nEach SubLocation object contains:
Use the AccessCode as the API key in header authentication method.
HMAC-SHA256 signature calculation (hash-based message authentication code) uses a secret key to generate a unique signature for a message. The signature is then used to verify the authenticity of the message.
\n![http://static.redtea.io//hedy/qrcodes/image/d6dbada5054a4dfeb941e601327a4b42.png](\"http://static.redtea.io//hedy/qrcodes/image/d6dbada5054a4dfeb941e601327a4b42.png\"){kind=link}
// Concatenate RT-Timestamp, RT-RequestID, RT-AccessCode, and requestBody into one string.\n// This string, signStr, will be used as the data to hash in the HMAC-SHA256 function.\nString signStr = RT-Timestamp + RT-RequestID + RT-AccessCode + requestBody\n// Generate an HMAC-SHA256 hash of the signStr using the secretKey. \n// The resulting hash is converted to all lowercase characters for standardization purposes.\nsign = HMACSha256(signStr, secretKey).toLowerCase();\n\nTimestamp=1628670421\nRequestID=4ce9d9cdac9e4e17b3a2c66c358c1ce2\nAccessCode=11111\nSecretKey=1111\nRequestBody={\"imsi\":\"326543826\"}\nsignStr=16286704214ce9d9cdac9e4e17b3a2c66c358c1ce211111{\"imsi\":\"326543826\"}\nSignature=7EB765E27DF5373DEA2DBC8C41A7D9557743E46C8054750F3D851B3FD01D0835\n\nAdding your webhook the first time will trigger a test webhook send. If you have a correctly working endpoint, you will receive an CHECK_HEALTH event. If our test send fails, your endpoint cannot be saved. To check a valid endpoint try https://webhook.site/
{\"notifyType\":\"CHECK_HEALTH\",\"content\":{\"orderNo\":\"1234567890\",\"orderStatus\":\"Test\"}}**
Set your webhook URL to receive POST requests** in your account.
The notifications contain a notifyType field indicating the event category and a content object with specific details. Here are the types you can expect:
ORDER_STATUS
Trigger: Sent when an eSIM is created and ready for retrieval.
\nKey content field: orderStatus will be \"GOT_RESOURCE\".
Example Use: Used to know when your eSIM order is ready for download.
\nSMDP_EVENT
Trigger: Sent during real-time eSIM profile lifecycle events as they occur on the SM-DP+ server.
\nKey content fields:
eid: eUICC identifier of the device.
iccid: ID of the eSIM.
esimStatus: Current eSIM state (typically GOT_RESOURCE during provisioning, IN_USE when active).
smdpStatus: SM-DP+ server status indicating the specific operation:
DOWNLOAD: eSIM profile is being downloaded to the device.
INSTALLATION: eSIM profile is being installed on the device.
ENABLED: eSIM has been activated/enabled on the device.
DISABLED: eSIM profile has been deactivated/disabled on the device..
DELETED: eSIM profile has been removed from the device.
Example Use: Track real-time eSIM provisioning progress and profile state changes for detailed lifecycle monitoring.
\nESIM_STATUS
Trigger: Sent when the status of an individual eSIM changes after it has been allocated. This covers various lifecycle events.
\nKey content fields:
esimStatus: Indicates the current state. Common values observed include:
IN_USE: The eSIM has been installed/activated on a device.
USED_UP: The eSIM data allowance has been fully consumed.
USED_EXPIRED: The eSIM data is used up, and expired.
UNUSED_EXPIRED: The eSIM expired with data remaining.
CANCEL: The eSIM has been canceled / refunded.
REVOKED: The eSIM profile has been revoked.
smdpStatus: SM-DP+ server status (e.g., ENABLED, DISABLED, RELEASED, DELETED, INSTALLATION).
Example Use: Track activation, data exhaustion, expiration, or cancellations for specific eSIMs and notify customers.
\nDATA_USAGE
Trigger: 3 data usage webhooks will be sent when reaching 50% (0.5) data used, 80%(0.8) data used and 90%(0.9) data used.
\nKey content fields:
totalVolume: Total data allowance in bytes.
orderUsage: Data used so far in bytes.
remain: Remaining data in bytes.
remainThreshold : Values can be: 0.5, 0.2 and 0.1
Example Use: Proactively notify end-users about low data balance.
\nVALIDITY_USAGE
Trigger: Sent when the remaining validity period of an active eSIM reaches 1 day.
\nKey content fields:
remain: The remaining validity duration (e.g., 1).
durationUnit: The unit for the duration (e.g., \"DAY\").
expiredTime: The exact timestamp when the eSIM will expire.
totalDuration: The original validity duration.
Example Use: Warn end-users that their plan is about to expire.
\nFor additional security, you can whitelist the following sender IPs:
\n3.1.131.226
54.254.74.88
18.136.190.97
18.136.60.197
18.136.19.137
Note: The content object structure may vary slightly. Always inspect the received payload to understand all available fields for each notifyType.
Look at our example webhook sending and test trigger form.
\n{\n \"notifyType\": \"ORDER_STATUS\",\n \"content\": {\n \"orderNo\": \"B23072016497499\",\n \"orderStatus\": \"GOT_RESOURCE\"\n }\n}\n\n{\n \"notifyType\": \"SMDP_EVENT\",\n \"eventGenerateTime\": \"2025-09-11T13:28:09+0000\",\n \"notifyId\": \"5fcc219e32dc484598d3fd700cf3738d\",\n \"content\": {\n \"eid\": \"89049032007108882600137544319616\",\n \"iccid\": \"8997250230000292199\",\n \"esimStatus\": \"GOT_RESOURCE\",\n \"smdpStatus\": \"DOWNLOAD\",\n \"orderNo\": \"B25091113270004\",\n \"esimTranNo\": \"25091113270004\",\n \"transactionId\": \"12068951785848-1-1\"\n }\n}\n\n{\n \"notifyType\": \"DATA_USAGE\",\n \"eventGenerateTime\": \"2025-07-21T10:57:28Z\",\n \"notifyId\": \"f776267e8d6745db8cc316e4c146ea0c\",\n \"content\": {\n \"orderNo\": \"B25052822150009\",\n \"transactionId\": \"unique_id_from_partner\",\n \"esimTranNo\": \"25052822150009\",\n \"iccid\": \"8943108170001029631\",\n \"totalVolume\": 53687091200,\n \"orderUsage\": 48335585458,\n \"remain\": 5351505742,\n \"lastUpdateTime\": \"2025-07-21T09:38:25Z\",\n \"remainThreshold\": 0.1\n }\n}\n\n{\n \"notifyType\": \"VALIDITY_USAGE\",\n \"content\": {\n \"orderNo\": \"B23072016497499\",\n \"transactionId\": \"Your_txn_id\",\n \"iccid\": \"894310817000000003\",\n \"durationUnit\": \"DAY\",\n \"totalDuration\": 30,\n \"expiredTime\": \"2024-01-11T08:10:19Z\",\n \"remain\": 1\n }\n}\n\n{\n \"notifyType\": \"ESIM_STATUS\",\n \"eventGenerateTime\": \"2025-08-09T00:23:45Z\",\n \"notifyId\": \"4038b3dfb1b050bf9f02501df67284f3\",\n \"content\": {\n \"orderNo\": \"B25080823490018\",\n \"esimTranNo\": \"25080323490020\",\n \"transactionId\": \"e23111e4d07746889c7bce41cf3f1b16\",\n \"iccid\": \"89852000263413436720\",\n \"esimStatus\": \"CANCEL\",\n \"smdpStatus\": \"RELEASED\"\n }\n}\n\n