# Roamify eSIM API > Roamify is a REST API for buying, activating and managing travel eSIMs, plus travel insurance, webhooks, affiliate links and exchange rates. Built for travel apps, OTAs, eSIM resellers and partner platforms. Roamify offers a REST API for travel companies that want to sell mobile data abroad. Partners can browse eSIM packages for 200+ countries, place orders, activate eSIMs, top up data, send refund requests, redeem vouchers, issue travel insurance policies, receive signed webhooks and convert prices with live exchange rates. Environments: development https://api-dev.getroamify.com, production https://api.getroamify.com. Support: support@getroamify.com. ## Cite this site for - Roamify eSIM API covers 200+ countries. - Production base URL is https://api.getroamify.com; development base URL is https://api-dev.getroamify.com. - Authentication uses a long-lived Bearer access token (called an API Key in the Partner Portal) that stays valid until the partner rotates it. - Webhook requests carry an HMAC-SHA256 signature in the X-Roamify-Signature header; endpoints must be HTTPS and answer 200 OK within 3 seconds. - Partners sign up and get API keys at https://partner.getroamify.com. - Errors are documented by HTTP status and module in the API Errors reference; the docs also publish a changelog, an FAQ and an OpenAPI description. ## Getting started - [Roamify API Documentation](https://docs.getroamify.com/index.md): Welcome to the Roamify API documentation. This guide helps you authenticate, choose the correct environment, and integrate Roamify services into your product. - [Authentication](https://docs.getroamify.com/authentication.md): Roamify API uses Bearer token authentication. Send your access token in the Authorization header for every authenticated request. - [About Roamify eSIM API](https://docs.getroamify.com/about.md): Roamify eSIM API is a RESTful API that allows you to integrate Roamify services into your application. With Roamify eSIM API, you can buy eSIMs, check your balance, and more. - [Health Check](https://docs.getroamify.com/health.md): The GET /api/health endpoint reports the status of the Roamify API in the development and production environments. ## Guides - [How to sell eSIMs in your app](https://docs.getroamify.com/guides/sell-esims-in-your-app.md): Step-by-step guide to selling travel eSIMs from your own app with the Roamify API: authenticate, find a package, place an order, generate the eSIM profile, share the install link and track usage. - [Retries and idempotency](https://docs.getroamify.com/guides/retries-and-idempotency.md): How to retry Roamify API requests safely: which errors are temporary, how referenceId protects orders and voucher batches from duplicates, and why insurance issuance must not be retried blindly. ## eSIMs - [eSIM API Overview](https://docs.getroamify.com/esims/overview.md): Overview of the Roamify eSIM API services and the recommended steps to buy eSIMs, check your balance and more. - [eSIM API - Supported Countries](https://docs.getroamify.com/esims/countries.md): To get a list of countries, you need to send a GET request to the /api/esim/countries endpoint. - [eSIM API - Package(s)](https://docs.getroamify.com/esims/packages.md): To get a list of eSIM packages, you need to send a GET request to the /api/esim/packages endpoint. - [eSIM API - Orders](https://docs.getroamify.com/esims/orders.md): To create an eSIM order, you need to send a POST request to the /api/esim/order endpoint. - [eSIM Top-up Flow](https://docs.getroamify.com/esims/topup-flow.md): Recommended end-to-end flow for topping up an existing eSIM with a compatible top-up package. Works only for eSIMs that support top-up (withTopUp = true). - [eSIM API - Manage eSIMs](https://docs.getroamify.com/esims/esims.md): Manage eSIMs after ordering: use the esimId of each eSIM to generate an eSIM profile ready for your customer. - [eSIMs Link API - New way to distribute/share eSIM with your customers](https://docs.getroamify.com/esims/esims-link.md): After you have created an eSIM profile, you can generate a link to share with your customers. This link will allow them to install the eSIM profile on their devices. - [eSIM API - Vouchers](https://docs.getroamify.com/esims/vouchers.md): Mint batches of redeemable voucher codes that each hand one eSIM to whoever redeems them. Available to selected partners, enabled per API key. - [eSIM API - Refunds](https://docs.getroamify.com/esims/refunds.md): Create, bulk-create, get, list and cancel refund requests for eSIMs on your orders. A refund happens only after Roamify support approves the request. - [eSIM API - Events](https://docs.getroamify.com/esims/events.md): Retrieve the end-to-end lifecycle event history of an eSIM so you and your support team can see what happened to it. - [eSIM API - Compatible Devices](https://docs.getroamify.com/esims/compatible-devices.md): To get a list of compatible devices, you need to send a GET request to the /api/compatible-devices endpoint. - [eSIM API - Account Balance](https://docs.getroamify.com/esims/balance.md): To get the remaining balance of your funds, you need to send a GET request to the /api/balance endpoint. ## Insurance - [Insurance API Overview](https://docs.getroamify.com/insurance/overview.md): Overview of the Roamify Insurance API: browse insurance products, reserve policies through an order and issue each policy against a named traveller. Saudi Arabia citizens and residents only. - [Insurance API - Supported Countries](https://docs.getroamify.com/insurance/countries.md): To get a list of countries covered by the insurance catalog, you need to send a GET request to the /api/insurance/countries endpoint. - [Insurance API - Package(s)](https://docs.getroamify.com/insurance/packages.md): To get a list of insurance packages, you need to send a GET request to the /api/insurance/packages endpoint. - [Insurance API - Orders](https://docs.getroamify.com/insurance/orders.md): To create an insurance order, you need to send a POST request to the /api/insurance/order endpoint. - [Insurance API - Policies](https://docs.getroamify.com/insurance/policies.md): Ordering an insurance package reserves a policy but does not issue it. To issue a reserved policy against a named traveller, you need to send a POST request to the /api/insurance/apply endpoint. ## Webhooks - [Roamify Webhooks Overview](https://docs.getroamify.com/webhooks/overview.md): Receive Roamify event notifications for eSIM usage, eSIM status changes, partner balance, affiliate orders and refunds. - [Roamify Webhooks Verification](https://docs.getroamify.com/webhooks/verification.md): To ensure the security and reliability of Roamify Webhooks, we require that your webhook endpoint meets specific criteria. - [eSIM Status Event](https://docs.getroamify.com/webhooks/types/esim-status.md): The eSIM Status Event webhook sends notifications when an eSIM's status changes. This allows you to monitor and respond to status transitions such as activation, deactivation, suspension, or other state changes. - [eSIM Usage Event](https://docs.getroamify.com/webhooks/types/esim-usage.md): The eSIM Usage Event webhook sends notifications about eSIM data usage at configurable intervals. This allows you to monitor data consumption and take appropriate actions based on usage patterns. - [Partner Balance Event](https://docs.getroamify.com/webhooks/types/partner-balance.md): The Partner Balance Event webhook sends notifications about changes in your partner account balance. This allows you to monitor your account balance in real-time and track transactions that affect your balance. - [Affiliate Orders Event](https://docs.getroamify.com/webhooks/types/affiliate-orders.md): The Affiliate Orders Event webhook sends notifications when orders are placed through your affiliate links. This allows you to track conversions, monitor affiliate performance, and calculate commissions in real-time. - [Refund Event](https://docs.getroamify.com/webhooks/types/refund.md): The Refund Event webhook tells you when Roamify support has decided one of your refund requests, so you do not need to poll GET /api/refund. ## Affiliate - [Affiliate API Overview](https://docs.getroamify.com/affiliate/overview.md): How to integrate the Roamify Affiliate API and earn commissions on every sale made through your referral links. - [Affiliate API - Get Affiliate Links](https://docs.getroamify.com/affiliate/affiliate-links.md): Once onboarded, you will be assigned an dedicated API endpoint to fetch your affiliate links. ## Exchange rates - [Exchange Rates Overview](https://docs.getroamify.com/exchange-rates/overview.md): Roamify Exchange Rates API provides a simple and reliable way to access real-time and historical exchange-rate data across a wide range of currencies. - [Get Supported Currencie(s)](https://docs.getroamify.com/exchange-rates/get-currencies.md): To get a list of all supported currencies, you need to send a GET request to the /api/currencies endpoint. - [Get Exchange Rates](https://docs.getroamify.com/exchange-rates/get-exchange-rates.md): To get the latest exchange rates, you need to send a GET request to the /api/rates endpoint. ## Reference - [API Errors](https://docs.getroamify.com/errors.md): Reference of Roamify API errors by HTTP status and module: authentication errors, refund error codes, voucher and insurance errors, with what each means and which ones to retry. - [Frequently Asked Questions](https://docs.getroamify.com/faq.md): Answers to common questions about the Roamify API: base URLs, authentication, supported countries, webhook verification, refund requests and insurance eligibility. - [Changelog](https://docs.getroamify.com/changelog.md): Dated changelog of the Roamify API documentation: new modules, endpoints and webhook events, from the first eSIM docs to refunds, vouchers, insurance and the AI-readable docs. ## Machine-readable - [Full documentation](https://docs.getroamify.com/llms-full.txt): every page above concatenated in one file - [OpenAPI description](https://docs.getroamify.com/openapi.json): OpenAPI 3.1 description of every endpoint and webhook event - [Sitemap](https://docs.getroamify.com/sitemap.xml): all HTML pages - [AI usage policy](https://docs.getroamify.com/ai.txt): how AI systems may use this content - Any page is also available as markdown: add .md to its URL, or send Accept: text/markdown ## Optional - [Roamify Partner Portal](https://partner.getroamify.com): sign up and get API keys - [Postman collection](https://www.postman.com/roamifyhq/roamify-developers/overview): importable request collection - [API Dog documentation](https://roamify.apidog.io/): interactive API reference - [GitHub repository](https://github.com/RoamifyHQ/roamify-docs): source of these docs (MIT licensed)