Ziqtel | Admin

v2.4.0 Production

API Documentation

Welcome to the Ziqtel Core API. Our REST-based interface allows MVNO partners to programmatically manage cellular subscriptions, SIM provisioning, real-time usage analytics, and financial settlements. Designed for high-throughput enterprise operations.

Quick Start

Learn how to issue your first API key and authenticate your application in under 5 minutes.

SDKs & Libraries

Pre-built wrappers for Node.js, Python, Go, and Ruby to accelerate your integration.

Authentication

All requests to the Ziqtel API must include a Bearer token in the Authorization header. You can generate and rotate production keys in the Settings > API Management panel.

# Authenticate with your API key
curl -X GET https://api.ziqtel.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Important: Never expose your production keys in client-side code or public repositories. Use environment variables to store credentials.

Rate Limits

To ensure platform stability, we enforce rate limits based on your subscription tier. Limits are calculated per API key on a rolling window.

Tier	Requests	Window
Standard	1,000	60 seconds
Scale	10,000	60 seconds
Enterprise	Unlimited	Custom

Error Codes

Ziqtel uses standard HTTP response codes to indicate the success or failure of an API request.

HTTP Status	Error Code	Description
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	Account suspended or insufficient permissions.
422	`validation_error`	Request payload failed schema validation.
429	`rate_limit_exceeded`	Too many requests hit the platform.

Webhooks

Subscribe to events to receive real-time notifications about SIM status changes, porting completions, and payment events.

Event Types

sim.activated Triggered when a physical SIM or eSIM profile is successfully activated.

port.completed Triggered when a number port-in request has been finalised by the donor network.

Security: Signing Secrets. All webhook payloads include a X-Ziqtel-Signature header. You must verify this HMAC-SHA256 signature using your webhook secret to ensure the payload originated from Ziqtel.

Versioning

The current production version is v2.4.0. We use Semantic Versioning (SemVer) and maintain backward compatibility for all minor versions.

Major: Breaking changes (e.g., v3.0.0). Requires migration.
Minor: New endpoints and additive changes (v2.4.x). Fully compatible.
Patch: Security fixes and optimizations.

List Customers

Returns a paginated list of all active and inactive customers registered under your MVNO account.

GET /v1/customers

Query Parameters

limit Integer Max number of objects returned (default 20, max 100).

status String Filter by status: active, suspended.

JSON Response

{
  "status": "success",
  "data": [
    {
      "id": "cust_81597",
      "name": "Elena Rodriguez",
      "msisdn": "+12025550198",
      "plan": "Ultimate_5G_Unlim",
      "created_at": "2023-11-14T10:45:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "dwc123xyz",
    "has_more": true
  }
}

Update Plan

Updates the subscription plan for a specific customer. Changes usually take effect on the next billing cycle unless immediate is set to true.

PATCH

Request Body

plan_id Required The unique ID of the new plan.

immediate Boolean Switch plan immediately (pro-rated charge applies).

Request Example

{
  "plan_id": "plan_pro_50gb_intl",
  "immediate": true,
  "reason": "Customer upgrade via portal"
}

SIM Inventory

Retrieve a list of unassigned SIM cards available in your inventory.

GET /v1/sims

{
  "sims": [
    { "iccid": "8901...", "status": "available", "type": "Tri-cut SIM" }
  ]
}

Get SIM Details

Retrieves detailed information about a physical or electronic SIM card by its ICCID.

GET

{
  "iccid": "8904101011118510720",
  "type": "eSIM",
  "status": "provisioned",
  "last_seen": "2023-11-20T08:12:44Z",
  "device": {
    "imei": "350003003003004",
    "model": "iPhone 15 Pro"
  }
}

Activate eSIM

Triggers the remote provisioning of an eSIM profile. This generates an LPA string or QR code for the end-user.

POST

// POST Payload
{
  "customer_id": "cust_92197",
  "eid": "89049032005008889999001122334455",
  "region": "USA-NE",
  "auto_renew": true
}

Porting

Initiate a Mobile Number Portability (MNP) request to transfer an existing number to Ziqtel.

POST

Parameters

msisdn The number being ported.

account_pin Transfer PIN from old carrier.

Response

{ "status": "submitted", "request_id": "port_5512" }

Plans & Bundles

List all available commercial plans, data bolt-ons, and international roaming bundles.

GET

{ "plans": [ { "id": "plan_unlim", "data_cap": "unlimited" } ] }

Usage Stats

Fetch granular data, voice, and SMS usage statistics for a specific subscription.

GET

Query Parameters

from ISO8601 Start date for metrics.

to ISO8601 End date for metrics.

Response

{
  "subscription_id": "sub_44301",
  "period": { "start": "2023-11-01", "end": "2023-11-30" },
  "data": {
    "used_mb": 14205,
    "limit_mb": 50000
  },
  "voice_minutes": 302,
  "sms_count": 88
}

Billing & Ledger

Audit account movements, service fees, and wholesale settlements for your MVNO partner account.

GET /v1/billing/ledger

{
  "balance": 12450.50,
  "currency": "USD",
  "entries": [ { "type": "debit", "amount": 4.99, "desc": "SIM activation fee" } ]
}