{"openapi":"3.1.0","info":{"title":"eSIM API","version":"v1","description":"Sell travel eSIMs for 200+ countries and regions: list the plans, buy one, and hand your customer the QR code and activation code from the same response. Orders are paid from your FlightOTA deposit and issued at once. Included in the Business and Enterprise API plans."},"servers":[{"url":"https://api.flightota.com/api/v1","description":"Production"},{"url":"https://sandbox.flightota.com/api/v1","description":"Sandbox"}],"security":[{"X-Api-Key":[],"X-Api-Secret":[]}],"paths":{"/ping":{"get":{"operationId":"esim-ping","summary":"Ping","description":"Call GET /ping first; it returns your agency code and the IP we saw.","tags":["Getting started"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"ok":true,"partner":"PTR-000020","key_id":"ak_test_your_key_id","environment":"test","from_ip":"203.0.113.10","server_time":"2026-09-22T13:25:02+00:00"}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Retry; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Retry; nothing was charged."}}}}}}}}}},"/esims/places":{"get":{"operationId":"esim-places","summary":"All places","description":"Countries first, then regions (Europe, Asia, Global…). from is the cheapest plan at your price. kind is country or region. A country's code is its ISO code; a region has its own code, as listed.","tags":["Places and plans"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"currency":"BDT","places":[{"code":"AE","name":"United Arab Emirates","kind":"country","image":"https://…/places/ae.png","plans":12,"from":{"amount":38500,"currency":"BDT"}}]}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Retry; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Retry; nothing was charged."}}}}}}}}}},"/esims/places/{code}":{"get":{"operationId":"esim-place","summary":"One place's plans","description":"One place's plans and prices. (Plan details are production data for the UAE; the price is illustrative, yours depends on your agreement.) A place with no plans answers 404 place_not_found.","tags":["Places and plans"],"parameters":[{"name":"code","in":"path","required":true,"description":"A place's code.","schema":{"type":"string"},"example":"AE"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"place":{"code":"AE","name":"United Arab Emirates","kind":"country","image":"https://…/places/ae.png","plans":[{"id":"burj-mobile-7days-1gb","title":"1 GB - 7 days","data":"1 GB","amount_mb":1024,"days":7,"unlimited":false,"voice":null,"text":null,"operator":"Burj Mobile","operator_image":"https://…/operators/burj-mobile.png","plan_type":"data","activation":"first-usage","kyc":false,"rechargeable":true,"info":["5G data-only eSIM.","Rechargeable online with no expiry.","Operates on the Etisalat network in the United Arab Emirates."],"coverage":["AE"],"price":{"amount":38500,"currency":"BDT"}}]}}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"404":{"description":"place_not_found: A place with no plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"place_not_found":{"value":{"error":{"code":"place_not_found","message":"A place with no plans."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Retry; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Retry; nothing was charged."}}}}}}}}}},"/esims/orders":{"post":{"operationId":"esim-order","summary":"Order an eSIM","description":"The deposit pays and the eSIM is issued in the same call. Rarely, the eSIM provider does not answer the order in time and it may still have been placed. The order is charged and comes back as \"status\": \"pending\" with \"state\": \"ticketing\" and no sims yet. Do not order it again: our team confirms it with the provider, then the SIM codes appear on GET /esims/orders/{order_ref}, or the charge is returned to your deposit. An eSIM can be installed only once: tell the traveller to install it before the trip, on Wi-Fi, and not to delete it.","tags":["Order an eSIM"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Repeating the same request with the same key returns the order already made and buys nothing more.","schema":{"type":"string"},"example":"sim-7731"}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"example":{"status":"issued","order":{"order_ref":"TFS-4K7PQ2MX","state":"issued","created_at":"2026-09-22T14:40:03Z","issued_at":"2026-09-22T14:40:05Z","client_reference":"SIM-7731","total":{"amount":38500,"currency":"BDT"},"place":{"code":"AE","name":"United Arab Emirates","kind":"country"},"plan":{"id":"burj-mobile-7days-1gb","title":"1 GB - 7 days","data":"1 GB","days":7,"activation":"first-usage","…":"…"},"quantity":1,"validity_days":7,"email":"guest@example.com","sims":[{"iccid":"8910300000000012341","lpa":"LPA:1$smdp.example.com$ABC-123-XYZ","smdp_address":"smdp.example.com","activation_code":"ABC-123-XYZ","confirmation_code":null,"qr_url":"https://…/qr/ABC-123-XYZ.png","apple_install_url":"https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$ABC-123-XYZ","apn":{"type":"automatic","value":"internet"},"roaming":true}],"installation":{"qr":"1. Go to Settings > Mobile Data…","manual":"1. Go to Settings > Mobile Data > Add eSIM > Enter details manually…"}}}}}},"202":{"description":"pending","content":{"application/json":{"example":{"status":"pending","order":{"order_ref":"TFS-…","state":"ticketing","sims":[],"…":"…"}}}}},"400":{"description":"idempotency_key_required: Add the header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"Add the header."}}}}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"402":{"description":"insufficient_funds: Deposit too low; nothing charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_funds":{"value":{"error":{"code":"insufficient_funds","message":"Deposit too low; nothing charged."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"409":{"description":"supplier_refused: The plan was not issued; nothing charged; choose another.\nduplicate_request: Key reused with another body.\nrequest_in_progress: Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_refused":{"value":{"error":{"code":"supplier_refused","message":"The plan was not issued; nothing charged; choose another."}}},"duplicate_request":{"value":{"error":{"code":"duplicate_request","message":"Key reused with another body."}}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"Still running."}}}}}}},"410":{"description":"plan_unavailable: The plan is no longer sold; load the place again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"plan_unavailable":{"value":{"error":{"code":"plan_unavailable","message":"The plan is no longer sold; load the place again."}}}}}}},"422":{"description":"validation_failed: See errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing charged; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing charged; retry."}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["place_code","plan_id","email"],"properties":{"place_code":{"type":"string","description":"From places, e.g. AE."},"plan_id":{"type":"string","description":"A plan's id."},"quantity":{"type":"object","description":"1–5, default 1. One SIM per traveller; all on the same plan."},"email":{"type":"string","description":"The traveller's e-mail; the eSIM and install guide are sent there."},"name":{"type":"string","description":"The traveller's name, for the e-mail."},"client_reference":{"type":"string","description":"Your own reference, up to 64 characters."}}},"example":{"place_code":"AE","plan_id":"burj-mobile-7days-1gb","quantity":1,"email":"guest@example.com","name":"Arif Rahman","client_reference":"SIM-7731"}}}}},"get":{"operationId":"esim-orders-list","summary":"List orders","description":"Newest first, 25 a page. An issued eSIM is final: it cannot be cancelled or refunded through the API. Top-ups and usage checks are not in the API yet.","tags":["Read and list orders"],"parameters":[{"name":"client_reference","in":"query","required":false,"description":"Your own reference.","schema":{"type":"string"}},{"name":"created_from","in":"query","required":false,"description":"Created on or after this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"created_to","in":"query","required":false,"description":"Created on or before this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"page","in":"query","required":false,"description":"The page.","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"per_page up to 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"orders":[{"order_ref":"TFS-4K7PQ2MX","state":"issued","…":"…"}],"page":1,"per_page":25,"total":1,"last_page":1}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Retry; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Retry; nothing was charged."}}}}}}}}}},"/esims/orders/{order_ref}":{"get":{"operationId":"esim-order-get","summary":"Read an order","description":"Returns the order in the shape above, with the SIM codes, any time. Another agency's reference answers 404 order_not_found.","tags":["Read and list orders"],"parameters":[{"name":"order_ref","in":"path","required":true,"description":"The order reference, TFS-XXXXXXXX.","schema":{"type":"string"},"example":"TFS-4K7PQ2MX"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"order":{"order_ref":"TFS-4K7PQ2MX","state":"issued","…":"the shape above, with the SIM codes"}}}}},"401":{"description":"unauthenticated: Check the key and secret; issue a new key if revoked.\ncredential_inactive: Check the key and secret; issue a new key if revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Check the key and secret; issue a new key if revoked."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Check the key and secret; issue a new key if revoked."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP.\nip_not_whitelisted: Whitelist your server's IP.\nproduct_not_allowed: The key is not enabled for eSIM; your API plan must include it.\npartner_inactive: Account or plan not active; live keys work after certification.\nsubscription_*: Account or plan not active; live keys work after certification.\nenvironment_not_activated: Account or plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for eSIM; your API plan must include it."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or plan not active; live keys work after certification."}}}}}}},"404":{"description":"order_not_found: Another agency's reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"order_not_found":{"value":{"error":{"code":"order_not_found","message":"Another agency's reference."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Retry; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Retry; nothing was charged."}}}}}}}}}}},"components":{"securitySchemes":{"X-Api-Key":{"type":"apiKey","in":"header","name":"X-Api-Key"},"X-Api-Secret":{"type":"apiKey","in":"header","name":"X-Api-Secret"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}