Spenza API

Build powerful mobile subscription management applications with our comprehensive REST APIs. Manage SIMs, subscriptions, eSIMs, and more.

Authentication

Secure API access with Bearer token authentication

SIM Management

Retrieve SIM information and validate ICCID/IMEI

Plans

Browse and purchase mobile plans

Subscriptions

Activate, cancel, and manage subscriptions

eSIM

Purchase and provision eSIM profiles

Usage

Monitor data, voice, and SMS usage

Webhooks

Receive real-time event notifications

SIP Configuration

Configure voice over IP settings

Authentication

All API calls require authentication using a Bearer Token. You must first obtain this token using the Authentication API.

GET /api/v1/authenticate

Required Headers

Header Value Description
Authorization Bearer YOUR_TOKEN The access token obtained from Authentication API
Content-Type application/json All requests must send and receive JSON

Request Body

JSON 
{
    "key": "api-key",
    "secret": "api-secret"
}

Response

Response 
{
    "message": "Authentication Success.",
    "accessToken": "Your Auth Token for other APIs.",
    "expiration": "token expiration time"
}

Note: Replace YOUR_TOKEN with the actual access token received from the Authentication API.

Get SIM by ICCID

Retrieve detailed SIM card information using the ICCID (Integrated Circuit Card Identifier).

GET /api/v1/sim-by-iccid

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

Required Fields

Field Type Description
ICCID string The ICCID of the SIM card

Response

Response 
{
    "message": "Success.",
    "simInfo": {
        "status": {
            "user": "Assigned",
            "device": "Assigned"
        },
        "ICCID": "9999967890123456784",
        "network": "T-Mobile",
        "Operator": "T-Mobile",
        "phoneNumber": "78993093857",
        "phoneLineStatus": "ACTIVATED"
    }
}

Get Plan by ID

Retrieve plan details using a unique plan identifier.

GET /api/v1/plan-by-id

Request Parameters

Field Type Description
planId string Unique identifier for the plan

Purchase Plan

Purchase a mobile plan for a specific SIM card. You can choose to activate immediately or schedule for a later date.

POST /api/v1/purchase-plan

Request Body

JSON 
{
    "ICCID": "8901260853182965429",
    "productId": "product1",
    "activateNow": true,
    "scheduledDate": "2024-04-20"
}

Required Fields

Field Type Description
ICCID string The ICCID of the SIM card
productId string The ID of the plan to purchase
activateNow boolean Whether to activate the plan immediately
scheduledDate string Date to schedule activation (YYYY-MM-DD)

Response

Response 
{
    "message": "Success.",
    "subscription": {
        "planName": "EXPLAN_100",
        "planCode": "EXPLAN_001",
        "status": "ACTIVE",
        "startDate": "2022-08-21T04:24:05.000Z",
        "endDate": "2022-11-21T04:24:05.000Z",
        "autoTopUp": true,
        "subId": "1663734246474",
        "Operator": "T-Mobile",
        "orderId": "1739-597673-2114"
    }
}

Activate Subscription

Activate a pending subscription for a SIM card.

PUT /api/v1/activate-subscription

Request Body

JSON 
{
    "ICCID": "8901260853182965429",
    "productId": "product1"
}

Required Fields

Field Type Description
ICCID string The ICCID of the SIM card
productId string The ID of the plan to activate

Response

Response 
{
    "message": "Success",
    "subscription": {
        "planName": "EXPLAN_101",
        "status": "ACTIVE",
        "subId": "1663734246474",
        "Operator": "T-Mobile"
    }
}

Cancel Subscription

Cancel an active subscription for a SIM card.

POST /api/v1/cancel-subscription

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

Response

Response 
{
    "message": "Subscription Cancelled.",
    "subscription": {
        "status": "CANCELLED",
        "subId": "1663734246474"
    }
}

Get Usage

Retrieve current usage information for a subscription including data, calls, and SMS.

POST /api/v1/telco/getUsage

Request Body

JSON 
{
    "subId": "1745863440782"
}

Required Fields

Field Type Description
subId string The subscription ID (from subId field of subscription)

Response

Response 
{
    "result": {
        "usageData": 0,
        "usageCalls": 0,
        "usageSms": 0,
        "telcoStatus": "ACTIVATED",
        "network": "Verizon"
    }
}

Get Subscription by ICCID

Retrieve subscription details for a SIM card using its ICCID.

GET /api/v1/subscription-by-iccid

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

Response

Response 
{
    "message": "Success.",
    "subscription": {
        "planName": "T-Mobile100",
        "planCode": "T-Mobile0001",
        "status": "Pending",
        "startDate": "2022-09-21T04:24:05.000Z",
        "endDate": "2022-10-21T04:24:05.000Z",
        "autoTopUp": true,
        "subId": "1663734246473",
        "Operator": "T-Mobile"
    }
}

Renew Phone Number

Request a new phone number for the specified SIM card. This endpoint is rate-limited based on your plan configuration.

POST /api/v1/renew-phone-number

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

Rate Limits: This endpoint is subject to monthly rate limits based on your plan configuration. IP addresses are monitored for security purposes.

Response

Response 
{
    "message": "Request placed successfully, new number will be assigned soon"
}

Validate ICCID (Public)

Validates the format and checksum of an ICCID. This is a public endpoint and does not require authentication.

POST /api/v1/public/validate-iccid

Request Body

JSON 
{
    "ICCID": "8901260853182965429"
}

Response

Response 
{
    "isValid": true,
    "message": "Valid ICCID."
}

Validate IMEI (Public)

Validates the format and Luhn checksum of an IMEI. This is a public endpoint and does not require authentication.

POST /api/v1/public/validate-imei

Request Body

JSON 
{
    "IMEI": "356938035643809"
}

Response

Response 
{
    "isValid": true,
    "message": "Valid IMEI."
}

Purchase eSIM (Async)

Initiates asynchronous eSIM purchase and phone number provisioning. The API accepts optional user information.

POST /api/v1/purchase-esim

Request Body - Basic

JSON 
{
    "imei": "451014850281267",
    "simId": "TEST_SPENZA"
}

Request Body - With User Info

JSON 
{
    "imei": "451014850281267",
    "simId": "SpenzaJ_ESIM",
    "user": {
        "name": "John Doe",
        "email": "john@example.com"
    }
}

Response

Response 
{
    "message": "eSIM purchase initiated",
    "transactionId": "txn_123456789"
}

Get eSIM Purchase Status

Check the status of an asynchronous eSIM purchase transaction.

GET /api/v1/esim-purchase-status

Request Parameters

Field Type Description
transactionId string The transaction ID from purchase-esim response

Register Webhook

Register a webhook endpoint to receive real-time notifications for various events.

POST /api/v1/webhook/register

Request Body

JSON 
{
    "url": "https://your-server.com/webhook",
    "events": ["subscription.activated", "subscription.cancelled"]
}

List Webhooks

Retrieve a list of all registered webhooks for your account.

GET /api/v1/webhook/list

Delete Webhook

Remove a registered webhook endpoint.

DELETE /api/v1/webhook/delete

Request Body

JSON 
{
    "webhookId": "wh_123456789"
}

Register SIP Configuration

Register a SIP configuration for voice over IP services.

POST /api/v1/sip/register

Request Body

JSON 
{
    "sipServer": "sip.example.com",
    "username": "sipuser",
    "password": "sippassword"
}

Get SIP Configuration

Retrieve the current SIP configuration for your account.

GET /api/v1/sip/config

Delete SIP Configuration

Remove the SIP configuration from your account.

DELETE /api/v1/sip/config

V3 Async APIs Introduction

V3 APIs provide asynchronous operations for long-running tasks. These endpoints return a transaction ID immediately, allowing you to poll for the result or receive updates via webhooks.

Benefits of V3 APIs: Better handling of network timeouts, improved reliability, real-time status updates via webhooks, and ability to track transaction history.

Get Transaction Status

Check the status of any V3 async transaction.

GET /api/v3/transaction-status

Request Parameters

Field Type Description
transactionId string The transaction ID returned from async API calls

Response

Response 
{
    "transactionId": "txn_123456789",
    "status": "completed",
    "result": { ... }
}

Purchase Plan (Async)

Asynchronously purchase a mobile plan. Returns a transaction ID for status polling.

POST /api/v3/purchase-plan

Request Body

JSON 
{
    "ICCID": "8901260853182965429",
    "productId": "product1",
    "activateNow": true
}

Activate Subscription (Async)

Asynchronously activate a pending subscription.

PUT /api/v3/activate-subscription

Request Body

JSON 
{
    "ICCID": "8901260853182965429",
    "productId": "product1"
}

Cancel Subscription (Async)

Asynchronously cancel an active subscription.

POST /api/v3/cancel-subscription

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

eSIM Purchase (Async)

Asynchronously purchase and provision an eSIM profile.

POST /api/v3/purchase-esim

Request Body

JSON 
{
    "imei": "451014850281267",
    "simId": "SpenzaJ_ESIM"
}

Renew Phone Number (Async)

Asynchronously request a new phone number for a SIM card.

POST /api/v3/renew-phone-number

Request Body

JSON 
{
    "ICCID": "9999967890123456789"
}

Error Codes

The Spenza API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Status Description
200 OK Request succeeded
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing authentication token
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Error Response Format

Error Response 
{
    "error": {
        "code": "INVALID_ICCID",
        "message": "The provided ICCID is invalid"
    }
}