Firsty API

Our platform gives you everything you need to embed mobile connectivity directly into your product experience, without dealing with carriers, infrastructure, or operational complexity. With the Firsty API, you can seamlessly provision, activate, and manage mobile plans for your customers in just a few lines of code. From onboarding and (e)SIM activation to billing, usage tracking, and full lifecycle management, everything is handled through a clean, developer-friendly interface. Whether you're building for smartphones, smartwatches, tablets, or other connected devices, Firsty makes it effortless to offer wireless subscriptions under your own brand. You stay in control of the customer relationship while we handle the carrier integrations behind the scenes. Launch faster, operate more efficiently, and deliver a fully integrated connectivity experience - all powered by Firsty.

Security & Compliance

Firsty is ISO 27001 certified, ensuring enterprise-grade information security management across our platform and operations.

Authentication

The Firsty API uses OAuth2 Client Credentials flow for authentication. All API endpoints (except /auth/token) require a valid Bearer token.

How to authenticate:

1. Contact Firsty support to receive your client_id (your 6-digit client reference) and client_secret
2. Call POST /auth/token with your credentials to obtain an access token
3. Include the token in the Authorization header as Bearer {token}
4. Tokens are valid for 24 hours. Request a new token when expired.

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Idempotency

Mutating endpoints (POST, PATCH) support an optional X-Idempotency-Key header. If you retry a request with the same key within 48 hours, the API will return the cached original response without duplicating side effects. Returns 409 Conflict if a request with the same key is still being processed, or 422 if the key was previously used with a different request body.

Example:

X-Idempotency-Key: unique-request-identifier-123

Rate Limiting

API requests are rate-limited per client to ensure fair usage and system stability.

Default Limits:

• General endpoints: 10 requests per second
• Authentication endpoint (/auth/token): 30 requests per second

Rate Limit Headers: Successful API responses (2xx, 4xx except 429) may include rate limit informational headers. Rate limit exceeded responses (429) always include these headers:

• X-RateLimit-Limit: Maximum requests allowed in the window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets

When Exceeded: If you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Identifiers

The API uses various identifiers to reference resources (e.g., profileReference, esimReference, packageReference, planReference).

Important: Treat all identifiers as opaque strings. Do not parse, decode, or make assumptions about their internal structure. The format may change without notice, and any code that depends on parsing identifiers will break.

Best Practices:

• Store identifiers exactly as received from the API
• Use identifiers only for API calls and database keys
• Never parse or extract meaning from identifier formats
• Rely on API responses for metadata (don't try to infer from identifiers)

Plans

Plans define the standardized specifications of a package - including data allowance, speed, validity period, and supported regions. They serve as the blueprint that ensures consistency across your connectivity products. A package is a specific instance of a plan. While the plan defines the structure and rules, the package represents an individual subscription created from that plan and assigned to a customer.

Webhooks

Configure your webhook endpoint to receive real-time notifications for:

• eSIM Events: eSIM assigned, downloaded, installed, enabled, disabled, deleted, balance updated
• Package Events: Package created, activated, ended, usage milestones, exhausted, renewed
• Network Events: MCC switch (roaming between regions)
• Port-In Events: Port-in submitted, approved, rejected, completed, failed, cancelled

Webhook Security

All webhooks follow the Standard Webhooks specification with HMAC-SHA256 signatures.

Delivery & Retry Behavior

Retry Schedule:

• Attempt 1: Immediate
• Attempt 2: 30 seconds later
• Attempt 3: 1 minute later
• Attempt 4: 5 minutes later
• Attempt 5: 15 minutes later
• Attempt 6: 30 minutes later
• Attempt 7: 1 hour later
• Attempt 8: 2 hours later
• Attempt 9: 4 hours later
• Attempt 10: 8 hours later
• Maximum: 10 attempts over ~24 hours

Retry Triggers: A webhook is retried if your endpoint:

• Returns HTTP 5xx status code
• Returns HTTP 408 (Request Timeout)
• Times out (no response within 30 seconds)
• Has connection errors (DNS, TLS, TCP failures)

Successful Delivery: HTTP 2xx status code within 30 seconds

After Max Retries: After 10 failed attempts, the webhook delivery is marked as permanently failed and logged for manual review. You can request replay via support.

Event Ordering & Guarantees

Ordering: Events are delivered in best-effort order but are NOT guaranteed to arrive in the exact sequence they occurred. Design your webhook handler to be idempotent and handle out-of-order events.

Duplicate Detection: Each webhook has a unique webhook-id header. Store this ID to detect and skip duplicate deliveries.

Idempotency: Use the webhook-id as an idempotency key when processing events. The same webhook-id may be delivered multiple times (due to retries or network issues).

Replay Window: Webhook events are retained for 7 days. You can request replay of missed events within this window by contacting support.

Event Consistency: Some events may arrive before the corresponding API response completes. Always treat webhooks as the source of truth for asynchronous state changes.

See the Webhooks section below for detailed event schemas and security information.