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 423 Locked 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. Responses of rate-limited endpoints carry the RateLimit header (limit, remaining, and reset in seconds) and the RateLimit-Policy header describing the window, so you can watch the remaining budget before reaching the limit.

When Exceeded: You receive a 429 Too Many Requests response. Wait the number of seconds in Retry-After when it is present; otherwise back off exponentially. Add jitter so parallel workers do not retry in lockstep. Some 429 responses carry neither these headers nor a problem body, so handle a 429 by its status code.

Tracing

Every response carries an X-Request-Id header holding the trace ID for that request. Keep it alongside your own logs and include it when contacting support about a request.

The API also implements W3C Trace Context. Send a traceparent header to associate the request with your existing trace. A traceparent looks like 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01, where the second field is the trace ID - and the value you will get back in X-Request-Id.

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 ~16 hours

Retry Triggers: A webhook is retried if your endpoint:

• Returns any status other than 2xx, except 410 Gone
• Times out (no response within 30 seconds)
• Has connection errors (DNS, TLS, TCP failures)

Stopping Retries: A 410 Gone response stops the retries of that delivery immediately.

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.