API reference
Base URL for everything:
https://partner-api.esimfo.comEvery endpoint except the token exchange requires
Authorization: Bearer <access_token> and the scope listed on its page.
Endpoints
Section titled “Endpoints”| Method | Path | Scope | |
|---|---|---|---|
POST |
/oauth/token |
— | Get an access token |
GET |
/v1/catalog/catalogs |
catalog:read |
List catalogs with packages |
GET |
/v1/catalog/packages |
catalog:read |
List packages |
GET |
/v1/catalog/coverage |
catalog:read |
List coverage |
GET |
/v1/catalog/countries |
catalog:read |
List countries |
POST |
/v1/orders |
orders:write |
Create an order |
GET |
/v1/orders |
orders:read |
List orders |
GET |
/v1/orders/{id} |
orders:read |
Get an order |
GET |
/v1/esims |
esims:read |
List eSIMs |
GET |
/v1/esims/{iccid} |
esims:read |
Get an eSIM |
GET |
/v1/esims/{iccid}/usage |
esims:read |
Get remaining usage |
POST |
/v1/esims/{iccid}/customer |
esims:read |
Assign a customer |
POST |
/v1/esims/{iccid}/share-link |
esims:read |
Create a share link |
GET |
/v1/esims/{iccid}/topups |
esims:read |
List top-ups |
POST |
/v1/esims/{iccid}/topup |
esims:write |
Top up an eSIM |
POST |
/v1/esims/{iccid}/refund-request |
esims:write |
Request a refund |
GET |
/v1/refund-requests |
esims:read |
List refund requests |
GET |
/v1/refund-requests/{id} |
esims:read |
Get a refund request |
POST |
/v1/refund-requests/{id}/cancel |
esims:write |
Cancel a refund request |
GET |
/v1/balance |
balance:read |
Get your balance |
Conventions
Section titled “Conventions”Field names are snake_case. They are part of the contract and do not
change within /v1.
Money is a string. "12.40", never 12.4. Binary floating point cannot
represent decimal currency exactly, and a rounding error in a price is a
rounding error in someone’s invoice. Parse it with a decimal type.
Times are ISO 8601 in UTC. "2026-08-22T09:14:03.512Z".
Lists are cursor-paginated. Pass limit (max 200) and follow
next_cursor while has_more is true. Cursors are opaque — do not construct
one.
curl 'https://partner-api.esimfo.com/v1/orders?limit=100&cursor=ord_4b21c9e7' \ -H 'Authorization: Bearer esf_live_at_...'Errors share one shape with a stable code. See Errors.
Machine-readable spec
Section titled “Machine-readable spec”The OpenAPI 3.1 document is public and needs no key:
https://partner-api.esimfo.com/v1/openapi.jsonPoint your client generator at it. An interactive console lives at
https://partner-api.esimfo.com/v1/docs.