Build global eSIM connectivity into your product.

Before you start

The NXTL B2B REST API provides server-to-server endpoints for programmatic provisioning and management. Before integrating, ensure your environment meets these operational requirements:

Quick start

This sequence confirms the key, estimates the account impact and queues one eSIM without exposing a secret to the client.

1. Check the public health endpoint

GET /health is the only public operation. Use it to confirm that the API is reachable; it does not prove that your key, balance or quota is ready.

curl -sS "https://nxtlsim.com/api/v1/health"

2. Confirm the key and account

The response identifies the business account and the permissions available to this key. Store the key as a server-side secret.

curl -sS \
  -H "X-NXTL-Key: $NXTL_KEY" \
  "https://nxtlsim.com/api/v1/partner"

3. Estimate before issuing

Read the returned estimate and affordability result before starting a larger issuance request. Current fees and account capacity come from the API; do not duplicate them as permanent constants in your application.

curl -sS -X POST \
  -H "X-NXTL-Key: $NXTL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":1,"tier":"standard"}' \
  "https://nxtlsim.com/api/v1/esims/estimate"

4. Queue one reusable eSIM

A successful request returns HTTP 202 with a job ID. Issuance continues asynchronously. Poll GET /jobs/{id} or receive the esim.provisioned or esim.provision_failed event.

curl -sS -X POST \
  -H "X-NXTL-Key: $NXTL_KEY" \
  -H "Idempotency-Key: order-123-esim" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname":"Traveller 123",
    "tier":"standard",
    "client_reference":"ORDER-123"
  }' \
  "https://nxtlsim.com/api/v1/esims"

Authentication and scopes

Authenticate requests by passing your API key in the X-NXTL-Key header on every operation except GET /health. A newly created key returns its secret once; subsequent key listings expose only public identifiers. Store secrets in a managed server-side secret store and rotate or revoke them independently.

X-NXTL-Key: $NXTL_KEY

Build for safe retries and observable failures

Idempotency

Send Idempotency-Key on POST /esims, POST /esims/bulk-issue and POST /topup. Retrying the same operation with the same key returns the original outcome and adds Idempotent-Replayed: true. Generate a stable key from your own business operation—not a new random value for every retry.

Rate limits

Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on responses. Account configuration may change the limit, so do not hard-code one global request rate. Treat HTTP 429 as retryable after the indicated reset.

Request tracing

Every response includes X-Request-Id. Record it with failed operations and include it when asking NXTL support to investigate.

Issuance is asynchronous by design

A successful issuance request means NXTL accepted the work—not that a profile is already ready. Single and bulk issuance return a job ID. Use GET /jobs/{id} for status and per-row results, or subscribe to the relevant webhook events.

• • POST /esims queues one eSIM and accepts nickname, tier and client_reference.
• • POST /esims/bulk-issue accepts quantity from 1 to 1,000, plus tier, client_reference and metadata.
• • POST /esims/estimate checks the proposed issuance cost and balance impact without creating eSIMs.
• • GET /jobs lists asynchronous jobs.
• • GET /jobs/{id} returns the current state, summary and per-row outcomes where available.
• • /esim-requests/{job_id} is a legacy alias; use /jobs/{id} in new work.

Common integration recipes

Three end-to-end patterns reflecting standard operational architectures across travel, mobility, and device fleet deployments.

* Qualification: Roaming usage may be reported after activity. Thresholds are operational safeguards, not guaranteed instantaneous hard spending caps.

Manage the line after issuance

Repeated suspend and resume requests converge on the requested state. Termination is permanent and should require deliberate confirmation in your own workflow.

Treat money fields as accounting data, not display text

The business account uses a pooled balance. Current issuance fees, available balance, quota and account configuration must be read from the API instead of copied into application code.

Currency rules

Usage and pooled-balance records can contain USD or EUR depending on the eSIM profile generation and transaction. Read currency and amount as the native pair. Usage/CDR events also expose amount_usd and amount_eur where available; one converted field may be zero when it is not the native accounting amount, so zero must not be interpreted as free usage.

Display conversion can be requested with ?currency=EUR or Accept-Currency: EUR where supported, while canonical accounting fields remain available alongside. Preserve the native currency and amount in your ledger.

Reconcile usage at the level your operation needs

Threshold model

• • Scope: balance, esim or legacy-compatible line
• • Metrics: balance_below, line_usage_pct, line_usage_usd_today
• • Period: instant, daily, weekly, monthly
• • Action: notify or suspend

Create, update and remove rules through /thresholds. Keep the operational caveat visible: network usage records are not guaranteed to arrive in real time.

Webhooks and signed event delivery

NXTL delivers asynchronous lifecycle and billing events to your registered HTTPS webhook endpoint. Every inbound request includes the X-NXTL-Signature-V1 header containing the delivery timestamp and an HMAC-SHA256 signature calculated over {timestamp}.{raw_json_body} using your active webhook secret.

Verification Code Samples

const crypto = require('crypto');

function verifyNxtlWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  
  // Format: t=<unix_timestamp>,v1=<hex_hmac_sha256>
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.slice(2);
  const v1 = parts.find(p => p.startsWith('v1='))?.slice(3);
  
  if (!timestamp || !v1) return false;
  
  // Validate v1 is exactly 64 hexadecimal characters
  if (v1.length !== 64 || !/^[0-9a-f]{64}$/i.test(v1)) {
    return false;
  }
  
  // Reconstruct signed payload
  const signedPayload = `${timestamp}.${rawBody}`;
  const computedHex = crypto
    .createHmac('sha256', secret)
    .update(signedPayload, 'utf8')
    .digest('hex');
    
  const expectedBuf = Buffer.from(computedHex, 'hex');
  const suppliedBuf = Buffer.from(v1, 'hex');
  
  if (expectedBuf.length !== suppliedBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, suppliedBuf);
}

import hmac, hashlib

def verify_nxtl_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    parts = dict(part.split('=', 1) for part in signature_header.split(','))
    timestamp, v1 = parts.get('t'), parts.get('v1')
    if not timestamp or not v1 or len(v1) != 64:
        return False
    signed_payload = f"{timestamp}.".encode('utf-8') + raw_body
    computed_hex = hmac.new(secret.encode('utf-8'), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed_hex, v1)

function verify_nxtl_webhook(string $raw_body, string $signature_header, string $secret): bool {
    parse_str(str_replace(',', '&', $signature_header), $parts);
    $timestamp = $parts['t'] ?? '';
    $v1        = $parts['v1'] ?? '';
    if (empty($timestamp) || empty($v1) || strlen($v1) !== 64) {
        return false;
    }
    $signed_payload = $timestamp . '.' . $raw_body;
    $computed_hex   = hash_hmac('sha256', $signed_payload, $secret);
    return hash_equals($computed_hex, $v1);
}

Canonical Webhook Events (15 Events)

Make failures understandable and supportable

NXTL API responses use a structured error object with error, type, code, message, doc_url, optional details and a request ID. Some earlier lifecycle and balance operations can return a compact { "error": "code" } object. Treat the HTTP status as authoritative, handle optional fields defensively and retain the X-Request-Id response header when contacting support.

{
  "error": true,
  "type": "INSUFFICIENT_BALANCE",
  "code": "insufficient_balance",
  "message": "Pooled balance cannot cover the requested operation.",
  "doc_url": "https://nxtlsim.com/business-api/errors/insufficient_balance",
  "request_id": "req_8f1b2c3d4e5f",
  "details": {
    "required_usd": 11.99,
    "available_usd": 4.50
  }
}

Endpoint reference

All paths below are relative to https://nxtlsim.com/api/v1. This reference documents the current NXTL B2B API. Use the endpoint groups below for human-readable integration guidance and the published OpenAPI document for machine-readable tooling.

Current API boundaries