# Firsty Developer Portal

> Ship worldwide mobile data with one REST API. Data in 170 countries, calling to 200+, and a sandbox you can hit without a sales call.

API reference and error pages are linked as Markdown: each one also answers at its own URL plus `.md`.

## Docs

- [Credentials](https://developers.firsty.app/documentation/get-api-key): Claim sandbox credentials with the CLI, or go live via sales.
- [OpenAPI Spec](https://developers.firsty.app/documentation/openapi-spec): The machine-readable description of every endpoint.

### Getting started

- [Overview](https://developers.firsty.app/documentation): What the Firsty API does and how to make a first call.
- [Quickstart](https://developers.firsty.app/documentation/getting-started/quickstart): Activate your first eSIM in under five minutes.
- [Authentication](https://developers.firsty.app/documentation/getting-started/authentication): OAuth2 client credentials, tokens and environments.
- [Rate limits](https://developers.firsty.app/documentation/getting-started/rate-limits): Request ceilings, burst behaviour and backoff guidance.

### Core concepts

- [eSIM lifecycle](https://developers.firsty.app/documentation/concepts/esim-lifecycle): From provisioning to activation to expiry.
- [eSIM installation](https://developers.firsty.app/documentation/concepts/esim-installation): Deep links, QR codes and in-app install on iOS and Android.
- [Data plans](https://developers.firsty.app/documentation/concepts/data-plans): How allowances, regions and validity fit together.
- [Webhooks](https://developers.firsty.app/documentation/concepts/webhooks): Subscribe to activation and usage events.
- [Embedded web app](https://developers.firsty.app/documentation/concepts/embedded-web-app): Sign your own users into Firsty's hosted app with a signed JWT.

### Resources

- [eSIM and telecom glossary](https://developers.firsty.app/documentation/resources/glossary): Plain definitions of the eSIM, telecom and VoIP terms developers meet when integrating mobile data: IMSI, ICCID, eUICC, SM-DP+, LPA, SIP, SBC and more.

## API reference

### Essentials

- [Overview](https://developers.firsty.app/api-reference.md): The Partners API in full: worldwide eSIM and mobile data from one integration.
- [Authentication](https://developers.firsty.app/api-reference/authentication.md): Exchange your client ID and secret for a bearer token.
- [Errors](https://developers.firsty.app/api-reference/errors.md): RFC 9457 problem documents, and the responses any endpoint can return.

### Authentication

- [Get Access Token](https://developers.firsty.app/api-reference/authentication/get-access-token.md): POST

### Catalog

- [List available package plans](https://developers.firsty.app/api-reference/catalog/get-package-plans.md): GET
- [List available regions](https://developers.firsty.app/api-reference/catalog/get-regions.md): GET
- [List available eSIM variants](https://developers.firsty.app/api-reference/catalog/get-esim-variants.md): GET, Experimental
- [List compatible devices](https://developers.firsty.app/api-reference/catalog/list-compatible-devices.md): GET
- [Check device compatibility](https://developers.firsty.app/api-reference/catalog/check-device-compatibility.md): GET
- [Get network coverage](https://developers.firsty.app/api-reference/catalog/get-network-coverage.md): GET
- [List subscribable webhook event types](https://developers.firsty.app/api-reference/catalog/get-webhook-event-types.md): GET, Experimental

### Profile

- [List profiles](https://developers.firsty.app/api-reference/profile/list-profiles.md): GET, Experimental
- [Get profile](https://developers.firsty.app/api-reference/profile/get-profile.md): GET, Experimental
- [Update profile](https://developers.firsty.app/api-reference/profile/update-profile.md): PATCH, Experimental

### eSIM

- [Order an eSIM](https://developers.firsty.app/api-reference/esim/order-esim.md): POST
- [List eSIMs for a profile](https://developers.firsty.app/api-reference/esim/list-profile-esims.md): GET
- [Get eSIM details](https://developers.firsty.app/api-reference/esim/get-profile-esim.md): GET
- [Update eSIM lifecycle](https://developers.firsty.app/api-reference/esim/update-profile-esim-lifecycle.md): PATCH, Experimental
- [List eSIM status history](https://developers.firsty.app/api-reference/esim/list-profile-esim-updates.md): GET, Experimental

### Balance

- [Get eSIM balance](https://developers.firsty.app/api-reference/balance/get-esim-balance.md): GET, Experimental
- [Set eSIM balance](https://developers.firsty.app/api-reference/balance/set-esim-balance.md): PUT, Experimental
- [List eSIM balance updates](https://developers.firsty.app/api-reference/balance/list-esim-balance-updates.md): GET, Experimental
- [Create eSIM balance update](https://developers.firsty.app/api-reference/balance/create-esim-balance-update.md): POST, Experimental

### Usage

- [Get eSIM usage](https://developers.firsty.app/api-reference/usage/get-profile-esim-usage.md): GET
- [Get aggregated usage history](https://developers.firsty.app/api-reference/usage/get-profile-esim-usage-history.md): GET, Experimental
- [List usage sessions](https://developers.firsty.app/api-reference/usage/list-profile-esim-sessions.md): GET, Experimental

### Packages

- [List packages for an eSIM](https://developers.firsty.app/api-reference/packages/list-profile-esim-packages.md): GET
- [Order a package](https://developers.firsty.app/api-reference/packages/order-profile-esim-package.md): POST
- [Get package history](https://developers.firsty.app/api-reference/packages/get-profile-esim-package-history.md): GET
- [Get package details](https://developers.firsty.app/api-reference/packages/get-profile-esim-package.md): GET
- [Remove a package](https://developers.firsty.app/api-reference/packages/delete-profile-esim-package.md): DELETE

### Porting

- [List port-in requests](https://developers.firsty.app/api-reference/porting/list-port-ins.md): GET, Experimental
- [Create a corrected port-in request](https://developers.firsty.app/api-reference/porting/create-port-in.md): POST, Experimental
- [Get port-in details](https://developers.firsty.app/api-reference/porting/get-port-in.md): GET, Experimental
- [Cancel a port-in request](https://developers.firsty.app/api-reference/porting/cancel-port-in.md): POST, Experimental
- [Abandon porting and keep the temporary number](https://developers.firsty.app/api-reference/porting/abandon-port-in.md): POST, Experimental

### Number Registration

- [Get the number registration](https://developers.firsty.app/api-reference/number-registration/get-number-registration.md): GET, Experimental
- [Create or replace the number registration](https://developers.firsty.app/api-reference/number-registration/upsert-number-registration.md): POST, Experimental

### Webhooks

- [Overview](https://developers.firsty.app/api-reference/webhooks.md): Receive and verify eSIM, package and port-in events.
- [eSIM events](https://developers.firsty.app/api-reference/webhooks/esim.md)
- [Package events](https://developers.firsty.app/api-reference/webhooks/package.md)
- [Port-in events](https://developers.firsty.app/api-reference/webhooks/portin.md)

### Management

- [Get client](https://developers.firsty.app/api-reference/management/get-client.md): GET, Experimental
- [List webhook endpoints](https://developers.firsty.app/api-reference/management/get-client-webhooks.md): GET, Experimental
- [Create a webhook endpoint](https://developers.firsty.app/api-reference/management/create-client-webhook.md): POST, Experimental
- [Update a webhook endpoint](https://developers.firsty.app/api-reference/management/update-client-webhook.md): PATCH, Experimental
- [Delete a webhook endpoint](https://developers.firsty.app/api-reference/management/delete-client-webhook.md): DELETE, Experimental
- [Rotate a webhook endpoint's signing secret](https://developers.firsty.app/api-reference/management/rotate-client-webhook-secret.md): POST, Experimental
- [List webhook deliveries](https://developers.firsty.app/api-reference/management/get-client-webhook-deliveries.md): GET, Experimental
- [List CDR export targets](https://developers.firsty.app/api-reference/management/get-client-cdr-export-targets.md): GET, Experimental
- [List CDR export deliveries](https://developers.firsty.app/api-reference/management/get-client-cdr-export-deliveries.md): GET, Experimental

## Errors

- [API errors](https://developers.firsty.app/errors.md): Every Partners API error is an RFC 9457 problem document whose type field links to one of these pages. Each page explains what the error means and how to handle it.
- [Bad request](https://developers.firsty.app/errors/bad-request.md): The request was malformed or a parameter had an invalid value. The detail field says which one.
- [Validation failed](https://developers.firsty.app/errors/validation-failed.md): One or more fields in the request failed validation. The errors array lists each field and what is wrong with it.
- [Unauthorized](https://developers.firsty.app/errors/unauthorized.md): The request carried no usable credentials: the bearer token is missing, invalid or expired, or the client credentials were rejected.
- [Forbidden](https://developers.firsty.app/errors/forbidden.md): The credentials are valid but this operation is not allowed for your account. The detail field says why.
- [Not found](https://developers.firsty.app/errors/not-found.md): The resource in the request URL does not exist.
- [Conflict](https://developers.firsty.app/errors/conflict.md): The request is valid but conflicts with the current state of the resource. The detail field says which conflict you hit.
- [Unprocessable entity](https://developers.firsty.app/errors/unprocessable-entity.md): The request is well formed and valid, but the operation it asks for cannot be carried out. The detail field explains why.
- [Idempotency key reused](https://developers.firsty.app/errors/idempotency-key-reused.md): This X-Idempotency-Key was already used with a different request body within the last 48 hours.
- [Locked](https://developers.firsty.app/errors/locked.md): A request with the same X-Idempotency-Key is still being processed. Wait briefly, then retry with the same key.
- [Rate limit exceeded](https://developers.firsty.app/errors/rate-limit-exceeded.md): You have sent too many requests in the current window. Wait for the time in Retry-After, then try again.
- [Internal server error](https://developers.firsty.app/errors/internal-error.md): Something failed on Firsty's side. The request may or may not have taken effect, so verify state before re-attempting.
- [Service unavailable](https://developers.firsty.app/errors/service-unavailable.md): The resource is temporarily unable to handle the request. Wait a moment, then retry.

## Tools

- [OpenAPI spec](https://developers.firsty.app/api-reference/openapi.json): the whole API as one OpenAPI 3.1 file
- [Agent setup guide](https://developers.firsty.app/agents.md): walks a coding agent through installing the Firsty CLI and ordering a first eSIM
- [Firsty CLI on npm](https://www.npmjs.com/package/firsty)

## Optional

- [Firsty for business](https://www.firsty.app/business)
- [Talk to sales](https://developers.firsty.app/contact-sales): production access, volume pricing and partnerships