Spenza API

Getting Started

https://api-prod.spenza.com

# All authenticated endpoints require these headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

# Step 1: Get your API credentials from Spenza
# Step 2: Call /api/v1/authenticate to get access token
# Step 3: Use the token in all subsequent API calls

# Example: Authenticate first
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/authenticate' \
    -H 'Content-Type: application/json' \
    -d '{
    "key": "your-api-key",
    "secret": "your-api-secret"
}'

{
    "message": "Authentication Success.",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiration": "2024-01-16T10:30:00.000Z"
}

# Include the token in Authorization header
$ curl \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    -H 'Content-Type: application/json' \
    'https://api-prod.spenza.com/api/v1/sim-by-iccid'

Authentication Example

# Get your authentication token
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/authenticate' \
    -H 'Content-Type: application/json' \
    -d '{
    "key": "api-key",
    "secret": "api-secret"
}'

    
    Copy

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

# Use the received token in subsequent API calls
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/sim-by-iccid' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "9999967890123456789"
}'

    
    Copy

# Missing Fields
{
    "errors": [{
        "message": "Api Key and Secrets are Required Fields.",
        "fields": ["key", "secret"]
    }]
}

# Missing field key
{
    "errors": [{
        "message": "Api Key is Required Field.",
        "fields": ["key"]
    }]
}

# Missing field secret
{
    "errors": [{
        "message": "Api Secret is Required Field.",
        "fields": ["secret"]
    }]
}

# Invalid API Credentials
{
    "errors": [{
        "message": "Invalid Api Credentials."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Get SIM

# Retrieve SIM information using ICCID
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/sim-by-iccid' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "9999967890123456789"
}'

    
    Copy

{
    "message": "Success.",
    "simInfo": {
        "status": {
            "user": "Assigned",
            "device": "Assigned"
        },
        "operator": {
            "custNbr": null
        },
        "ICCID": "9999967890123456784",
        "activationCode": "",
        "source": "Other",
        "isDeleted": false,
        "recommendedPlan": "60af49af21647e2ca0b15f51",
        "_id": "632808a8e85110002e3ae629",
        "network": "T-Mobile",
        "Operator": "T-Mobile",
        "phoneNumber": "78993093857",
        "group": "63280750e85110002e3ae624",
        "account": "63280446e85110002e3ae54e",
        "phoneLineStatus": "ACTIVATED"
    }
}

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID is required field.",
        "field": "ICCID"
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Get Plan

# Retrieve plan information using planId
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/plan-by-id' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "planId": "AT0001"
}'

    
    Copy

{
    "message": "Success.",
    "plan": {
        "stripe": {
            "price": "price_1LgUXYAq7JKAyJICWrRooGBI"
        },
        "productName": "AT&T100",
        "category": "PLANS",
        "Operator": "AT&T",
        "network": "AT&T",
        "zone": "US",
        "validityDays": 30,
        "dataMB": 10,
        "speed": "4G",
        "price": 10,
        "inStock": 0,
        "durationType": "Monthly",
        "isDeleted": false,
        "_id": "63184df1203d4994052869f7",
        "description": "AT&T Plan 1",
        "productId": "AT0001",
        "feature": []
    }
}

# Missing field planId
{
    "errors": [{
        "message": "Plan Id is Required.",
        "field": "planId"
    }]
}

# Plan Not Found
{
    "errors": [{
        "message": "Plan Not Found."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Purchase Plan

# Purchase a plan using ICCID, productId and schedule info
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/purchase-plan' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "8901260853182965429",
    "productId": "product1",
    "activateNow": true,
    "scheduledDate": "2024-04-20"
}'

    
    Copy

{
    "message": "Success.",
    "subscription": {
        "stripe": {
            "subId": "sub_1LkKThAq7JKDyJICNJ3l1WWv",
            "scheduleId": null,
            "price": null
        },
        "operatorRes": {
            "MDN": null,
            "description": null
        },
        "planName": "EXPLAN_100",
        "planCode": "EXPLAN_001",
        "status": "ACTIVE",
        "initiatedDate": "2022-08-21T04:24:06.473Z",
        "startDate": "2022-08-21T04:24:05.000Z",
        "endDate": "2022-11-21T04:24:05.000Z",
        "scheduledDate": "2022-09-20T00:00:00.000Z",
        "cancelledDate": null,
        "autoTopUp": true,
        "subId": "1663734246474",
        "Operator": "T-Mobile",
        "network": "T-Mobile",
        "orderId": "1739-597673-2114"
    }
}

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID Key is Required Field.",
        "fields": ["ICCID"]
    }]
}

# Missing field productId
{
    "errors": [{
        "message": "productId is Required Field.",
        "fields": ["productId"]
    }]
}

# Missing field activateNow
{
    "errors": [{
        "message": "activateNow is Required Field.",
        "fields": ["activateNow"]
    }]
}

# Missing field scheduledDate
{
    "errors": [{
        "message": "scheduledDate is Required Field. Format:(YYYY-MM-DD)",
        "fields": ["scheduledDate"]
    }]
}

# Plan Not Found
{
    "errors": [{
        "message": "Plan Not Found."
    }]
}

# Operator Mismatch
{
    "errors": [{
        "message": "Sim Is Not Compatible. Please check Plan Operator and Sim Operator."
    }]
}

# Active Subscription Exists
{
    "errors": [{
        "message": "Sim Already has an Active Subscription."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something Went Wrong at our End. Our Engineers are being Notified about this Error."
    }]
}

Activate Subscription

# Activate a purchased plan
$ curl \
    -X PUT 'https://api-prod.spenza.com/api/v1/activate-subscription' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "8901260853182965429",
    "productId": "product1"
}'

    
    Copy

{
    "message": "Success",
    "subscription": {
        "stripe": {
            "subId": "sub_1LkKThAq7JKDyJICNJ3l1WWv",
            "scheduleId": null,
            "price": null
        },
        "operatorRes": {
            "MDN": null,
            "description": null
        },
        "planName": "EXPLAN_101",
        "planCode": "EXPLAN_003",
        "status": "ACTIVE",
        "initiatedDate": "2022-08-21T04:24:06.473Z",
        "startDate": "2022-08-21T04:24:05.000Z",
        "endDate": "2022-11-21T04:24:05.000Z",
        "scheduledDate": "2022-09-20T00:00:00.000Z",
        "autoTopUp": true,
        "subId": "1663734246474",
        "Operator": "T-Mobile",
        "network": "T-Mobile",
        "orderId": "1739-597673-2114"
    }
}

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID is Required Field.",
        "fields": ["ICCID"]
    }]
}

# Missing field productId
{
    "errors": [{
        "message": "productId is Required Field.",
        "fields": ["productId"]
    }]
}

# Plan Not Found
{
    "errors": [{
        "message": "Plan Not Found."
    }]
}

# Sim Not Found
{
    "errors": [{
        "message": "Sim Not Found."
    }]
}

# Subscription Not Found
{
    "errors": [{
        "message": "Subscription Not Found."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Cancel Subscription

# Cancel an active subscription
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/cancel-subscription' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "9999967890123456789"
}'

    
    Copy

{
    "message": "Subscription Cancelled.",
    "subscription": {
        "stripe": {
            "subId": "sub_1LkKThAq7JKDyJICNJ3l1WWv",
            "scheduleId": null,
            "price": null
        },
        "operatorRes": {
            "MDN": null,
            "description": null
        },
        "planName": "EXPLAN_100",
        "planCode": "EXPLAN_001",
        "status": "CANCELLED",
        "initiatedDate": "2022-08-21T04:24:06.473Z",
        "startDate": "2022-08-21T04:24:05.000Z",
        "endDate": "2022-11-21T04:24:05.000Z",
        "scheduledDate": "2022-09-20T00:00:00.000Z",
        "autoTopUp": true,
        "subId": "1663734246474",
        "Operator": "T-Mobile",
        "network": "T-Mobile",
        "orderId": "1739-597673-2114"
    }
}

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID is required field.",
        "fields": ["ICCID"]
    }]
}

# Sim Not Found
{
    "errors": [{
        "message": "Sim Not Found."
    }]
}

# Subscription Not Found
{
    "errors": [{
        "message": "Subscription Not Found."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Get Subscription

# Retrieve subscription by ICCID
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/subscription-by-iccid' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "9999967890123456789"
}'

    
    Copy

{
    "message": "Success.",
    "subscription": {
        "stripe": {
            "subId": "sub_1LkKThAq7JKAyJICNJ3l1WWv",
            "scheduleId": null,
            "price": null
        },
        "operatorRes": {
            "MDN": null,
            "description": null
        },
        "planName": "T-Mobile100",
        "planCode": "T-Mobile0001",
        "status": "Pending",
        "initiatedDate": "2022-09-21T04:24:06.473Z",
        "startDate": "2022-09-21T04:24:05.000Z",
        "endDate": "2022-10-21T04:24:05.000Z",
        "scheduledDate": "2022-09-20T00:00:00.000Z",
        "cancelledDate": null,
        "autoTopUp": true,
        "subId": "1663734246473",
        "Operator": "T-Mobile",
        "network": "T-Mobile",
        "sim": "632a916b961e53002e1298d7",
        "account": "63280446e85110002e3ae54e",
        "orderId": "1339-597673-2114"
    }
}

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID is required field.",
        "field": "ICCID"
    }]
}

# Sim Not Found
{
    "errors": [{
        "message": "Sim Not Found."
    }]
}

# Subscription Not Found
{
    "errors": [{
        "message": "Subscription Not Found."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something Went Wrong at our End. Our Engineers are being Notified about this Error."
    }]
}

Get Usage

# Retrieve the usage of a Sim
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/telco/getUsage' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "subId": "1745863440782"
}'

    
    Copy

{
    "result": {
        "usageData": 0,
        "usageCalls": 0,
        "usageSms": 0,
        "usageUpdatedAt": 1747223324287,
        "telcoStatus": "ACTIVATED",
        "usageDataConverted": {
            "format": "B",
            "value": 0
        },
        "network": "Verizon",
        "networkCode": "Verizon"
    }
}

# Missing field subId
{
    "errors": [{
        "message": "Subscription Id is a Required Field.",
        "fields": ["subId"]
    }]
}

# No Active Invoice
{
    "errors": [{
        "message": "Subscription Don't have any Active Invoices."
    }]
}

# Internal Server Error
{
    "errors": [{
        "message": "Something is Wrong at our end. Our Engineers are being Notified."
    }]
}

Renew Phone Number

# Request a new phone number for a SIM card
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/renew-phone-number' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "9999967890123456789"
}'

    
    Copy

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

# Missing field ICCID
{
    "errors": [{
        "message": "ICCID is required field.",
        "fields": ["ICCID"]
    }]
}

# Subscription Not Found
{
    "errors": [{
        "message": "Subscription Not Found. Please Create an Active Subscription First."
    }]
}

# Rate Limit Exceeded
{
    "errors": [{
        "message": "Monthly rate limit exceeded for renew phone number requests."
    }]
}

# Internal Server Error
{
    "error": "Something went wrong"
}

Validate ICCID

# Validate ICCID format (no auth required)
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/public/validate-iccid' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "8901260853182965429"
}'

    
    Copy

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

Validate IMEI

# Validate IMEI format (no auth required)
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/public/validate-imei' \
    -H 'Content-Type: application/json' \
    -d '{
    "IMEI": "356938035643809"
}'

    
    Copy

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

Purchase eSIM (Async)

# Purchase eSIM with IMEI and SIM ID only
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/purchase-esim' \
    -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "imei": "451014850281267",
    "simId": "TEST_SPENZA"
}'

    
    Copy

# Purchase eSIM with user information for number provisioning
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/purchase-esim' \
    -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "imei": "451014850281267",
    "simId": "SpenzaJ_ESIM",
    "user": {
        "name": "Testung",
        "email": "test+8@spenza.com",
        "phoneNumber": "2031134322",
        "address": "47 W 13th St",
        "city": "New York",
        "state": "New York",
        "zipcode": "10011"
    }
}'

    
    Copy

{
    "requestId": "64dfa874-f157-431a-a6db-d8e5a915ea12",
    "status": "PENDING",
    "message": "eSIM purchase initiated successfully"
}

# After successful eSIM purchase:
# 1. Subscription is created with PENDING status
# 2. Phone number is provisioned based on the user's ZIP code location
# 3. eSIM QR code is generated and sent to customer via email
# 4. Customer can activate eSIM by scanning the QR code

Get eSIM Purchase Status

# Poll for purchase status 
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/purchase-esim/550e8400-e29b-41d4-a716-446655440000' \
    -H 'Authorization: Bearer YOUR_JWT_TOKEN'

    
    Copy

{
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUCCESS",
    "result": {
        "mdn": "1234567890",
        "iccid": "89012345678901234567",
        "qrCode": "https://s3.amazonaws.com/esim-activation-code/customer-id/iccid-esim-activation-qrcode.png"
    },
    "createdAt": "2024-12-05T10:00:00.000Z",
    "updatedAt": "2024-12-05T10:00:45.000Z"
}

Register Webhook

# Register webhook for SMS and Voice events
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/webhooks/register' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "operator": "SpenzaJ",
    "cdpType": "SpenzaJ",
    "eventType": "both",
    "authentication": {
        "type": "basic",
        "username": "webhook-user",
        "password": "super-secret"
    },
    "webhookUrls": {
        "messageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
        "callbackMessageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
        "voiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
        "callbackVoiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af"
    },
    "retryPolicy": {
        "maxAttempts": 5,
        "backoffStrategy": "fixed",
        "initialDelaySeconds": 2,
        "maxDelaySeconds": 300
    },
    "status": "active",
    "description": "Combined SMS and Voice webhooks for production"
}'

    
    Copy

{
    "message": "Webhook registered",
    "registration": {
        "_id": "69146d70ed68e3890a45c228",
        "operator": "SpenzaJ",
        "cdpType": "SpenzaJ",
        "eventType": "both",
        "authentication": {
            "type": "basic",
            "username": "webhook-user"
        },
        "webhookUrls": {
            "messageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
            "callbackMessageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
            "voiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
            "callbackVoiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af"
        },
        "retryPolicy": {
            "maxAttempts": 5,
            "backoffStrategy": "fixed",
            "initialDelaySeconds": 2,
            "maxDelaySeconds": 300
        },
        "status": "active",
        "description": "Combined SMS and Voice webhooks for production",
        "createdAt": "2025-01-10T09:15:01.000Z",
        "updatedAt": "2025-01-10T09:15:01.000Z"
    }
}

Response objects always include both SMS and voice URL fields; unused fields are returned as null. Save the _id field to delete this registration later.

List Webhooks

# List registered webhooks
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/webhooks/registrations?eventType=both' \
    -H 'Authorization: Bearer YOUR_TOKEN'

    
    Copy

{
    "registrations": [
        {
            "_id": "69146d70ed68e3890a45c228",
            "operator": "SpenzaJ",
            "cdpType": "SpenzaJ",
            "eventType": "both",
            "authentication": {
                "type": "basic",
                "username": "webhook-user"
            },
            "webhookUrls": {
                "messageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
                "callbackMessageUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
                "voiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af",
                "callbackVoiceUrl": "https://webhook.site/dcc5393e-cb1e-4005-9e80-1c80b7a011af"
            },
            "retryPolicy": {
                "maxAttempts": 5,
                "backoffStrategy": "fixed",
                "initialDelaySeconds": 2,
                "maxDelaySeconds": 300
            },
            "status": "active",
            "description": "Combined SMS and Voice webhooks",
            "createdAt": "2025-01-10T09:15:01.000Z",
            "updatedAt": "2025-01-10T09:15:01.000Z"
        }
    ]
}

Each entry includes both SMS and voice URL fields. Unused fields are returned as null.

Delete Webhook

# Delete webhook registration by ID
$ curl \
    -X DELETE 'https://api-prod.spenza.com/api/v1/webhooks/registrations/69146d70ed68e3890a45c228' \
    -H 'Authorization: Bearer YOUR_TOKEN'

    
    Copy

{
    "message": "Webhook registration deleted successfully"
}

# Registration Not Found
{
    "error": "Webhook registration not found"
}

# Unauthorized
{
    "error": "Unauthorized"
}

Register SIP Config

# Register or update SIP configuration
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v1/customer/register-sip' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "sipIngressIp": "203.0.113.10",
    "sipPort": 5060,
    "transport": "udp",
    "codecs": ["ulaw", "alaw"],
    "didRanges": ["+1415000xxxx", "+1818444xxxx"],
    "allowedSourceIps": ["203.0.113.10", "203.0.113.11"]
}'

    
    Copy

{
    "message": "SIP configuration registered successfully",
    "sipConfig": {
        "sipIngressIp": "203.0.113.10",
        "sipPort": 5060,
        "transport": "udp",
        "codecs": ["ulaw", "alaw"],
        "didRanges": ["+1415000xxxx", "+1818444xxxx"],
        "allowedSourceIps": ["203.0.113.10", "203.0.113.11"]
    },
    "isSIPEnabled": true
}

Get SIP Config

# Retrieve your SIP configuration
$ curl \
    -X GET 'https://api-prod.spenza.com/api/v1/customer/register-sip' \
    -H 'Authorization: Bearer YOUR_TOKEN'

    
    Copy

{
    "isSIPEnabled": true,
    "sipConfig": {
        "sipIngressIp": "203.0.113.10",
        "sipPort": 5060,
        "transport": "udp",
        "codecs": ["ulaw", "alaw"],
        "didRanges": ["+1415000xxxx", "+1818444xxxx"],
        "allowedSourceIps": ["203.0.113.10", "203.0.113.11"]
    }
}

Delete SIP Config

# Delete SIP configuration and disable SIP
$ curl \
    -X DELETE 'https://api-prod.spenza.com/api/v1/customer/register-sip' \
    -H 'Authorization: Bearer YOUR_TOKEN'

    
    Copy

{
    "message": "SIP configuration deleted successfully"
}

V3 Async APIs

# Step 1: Initiate async operation
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/purchase-plan' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429",
    "productName": "Premium_Plan",
    "activateNow": true
}'

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432100_abc123/status",
    "message": "Transaction initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

$ curl \
    'https://api-prod.spenza.com/api/v3/transaction/v3_1698765432100_abc123/status'

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "status": "COMPLETED",
    "result": {
        "subscription": {
            "subscriptionId": "sub_12345",
            "status": "ACTIVE"
        }
    },
    "timestamp": "2024-01-15T10:32:00.000Z"
}

Get Transaction Status

# Check transaction status (no auth required)
$ curl \
    'https://api-prod.spenza.com/api/v3/transaction/v3_1698765432100_abc123/status'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "status": "PENDING",
    "message": "Transaction is pending",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "status": "COMPLETED",
    "result": {
        "subscription": {
            "subscriptionId": "sub_12345",
            "status": "ACTIVE"
        }
    },
    "processingStartedAt": "2024-01-15T10:30:01.000Z",
    "processingCompletedAt": "2024-01-15T10:32:00.000Z"
}

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "status": "FAILED",
    "error": "Insufficient balance",
    "timestamp": "2024-01-15T10:31:00.000Z"
}

Purchase Plan (V3 Async)

# Initiate async plan purchase
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/purchase-plan' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429",
    "productName": "Premium_Plan_100GB",
    "activateNow": true
}'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432100_abc123",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432100_abc123/status",
    "message": "Transaction initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/purchase-plan' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429",
    "productName": "Premium_Plan",
    "scheduleDate": "2024-04-20"
}'

Activate Subscription (V3 Async)

# Activate subscription asynchronously
$ curl \
    -X PUT 'https://api-prod.spenza.com/api/v3/activate-subscription' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429",
    "productId": "product_12345"
}'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432101_def456",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432101_def456/status",
    "message": "Activation initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

Cancel Subscription (V3 Async)

# Cancel subscription asynchronously
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/cancel-subscription' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429"
}'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432102_ghi789",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432102_ghi789/status",
    "message": "Cancellation initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

eSIM Purchase (V3 Async)

# Initiate eSIM purchase (can take up to 45 minutes)
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/esim-purchase' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "deviceId": "device_12345",
    "planId": "plan_67890",
    "imei": "356938035643809",
    "activateNow": true
}'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432103_jkl012",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432103_jkl012/status",
    "message": "eSIM purchase initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

{
    "success": true,
    "transactionId": "v3_1698765432103_jkl012",
    "status": "COMPLETED",
    "result": {
        "mdn": "1234567890",
        "iccid": "89012345678901234567",
        "qrCode": "https://s3.amazonaws.com/esim-qr-codes/abc123.png"
    }
}

Renew Phone Number (V3 Async)

# Request new phone number asynchronously
$ curl \
    -X POST 'https://api-prod.spenza.com/api/v3/renew-phone-number' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "iccid": "8901260853182965429"
}'

    
    Copy

{
    "success": true,
    "transactionId": "v3_1698765432104_mno345",
    "statusEndpoint": "/api/v3/transaction/v3_1698765432104_mno345/status",
    "message": "Phone number renewal initiated",
    "timestamp": "2024-01-15T10:30:00.000Z"
}

{
    "success": true,
    "transactionId": "v3_1698765432104_mno345",
    "status": "COMPLETED",
    "result": {
        "newPhoneNumber": "+15551234567",
        "iccid": "8901260853182965429"
    }
}

Error Examples

{
    "errors": [{
        "message": "Missing required field: ICCID",
        "fields": ["ICCID"]
    }]
}

{
    "statusCode": 401,
    "message": "Invalid or expired authentication token",
    "error": "Unauthorized"
}

{
    "statusCode": 403,
    "message": "Access denied. Insufficient permissions.",
    "error": "Forbidden"
}

{
    "statusCode": 404,
    "message": "Resource not found",
    "error": "Not Found"
}

{
    "statusCode": 429,
    "message": "Monthly rate limit exceeded for this operation",
    "error": "Too Many Requests",
    "retryAfter": "2024-02-01T00:00:00.000Z"
}

{
    "statusCode": 500,
    "message": "Something went wrong at our end. Our engineers are being notified.",
    "error": "Internal Server Error"
}

# Always check the HTTP status code
$ curl \
    -w '\nHTTP Status: %{http_code}\n' \
    -X GET 'https://api-prod.spenza.com/api/v1/sim-by-iccid' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
    "ICCID": "8901260853182965429"
}'