Spenza provides various APIs to manage the mobile subscriptions offered in the Spenza marketplace. This document provides the information required to interact with Spenza APIs.
Authentication Headers
All API endpoints (except the authentication endpoint) require a Bearer token in the Authorization header. You must first obtain this token using the Authentication API.
Required Headers
Header
Value
Description
Authorization
Bearer YOUR_TOKEN
The access token obtained from the Authentication API
Requests a new phone number for the specified SIM card. This endpoint is rate-limited based on your plan configuration.
Request Body
{
"ICCID": "9999967890123456789"
}
Required Fields
Field
Type
Description
ICCID
string
The ICCID of the SIM card
Rate Limiting & IP Restrictions
Monthly Rate Limits: This endpoint is subject to monthly rate limits based on your plan configuration. The limit is defined in the plan's apiLimits.renewPhoneNumber property. If no limit is set, all requests are allowed.
IP Tracking: All requests are logged with the originating IP address from the x-forwarded-for header or connection IP. IP addresses are monitored for security and auditing purposes.
Response
{
"message": "Request placed successfully, new number will be assigned soon"
}
Validate ICCID (Public)
POST/api/v1/public/validate-iccid
Validates the format and checksum of an ICCID. This is a public endpoint and does not require authentication.
Request Body
{
"ICCID": "8901260853182965429"
}
Required Fields
Field
Type
Description
ICCID
string
SIM card ICCID to validate
Response
{
"isValid": true,
"message": "Valid ICCID."
}
Validate IMEI (Public)
POST/api/v1/public/validate-imei
Validates the format and Luhn checksum of an IMEI. This is a public endpoint and does not require authentication.
Request Body
{
"IMEI": "356938035643809"
}
Required Fields
Field
Type
Description
IMEI
string
Device IMEI to validate
Response
{
"isValid": true,
"message": "Valid IMEI."
}
Error Codes
HTTP Code
Message
Description
400
Missing Fields
Required fields are missing in the request
400
Invalid API Credentials
The provided API credentials are invalid
400
Plan Not Found
The requested plan does not exist
400
Sim Not Found
The requested SIM does not exist
400
Subscription Not Found
The requested subscription does not exist
429
Rate Limit Exceeded
Monthly rate limit exceeded for API requests
401
Unauthorized
Invalid or missing authentication token
403
Forbidden
Access denied or insufficient permissions
500
Internal Server Error
Something went wrong at our end
Authentication Example
# Request
# First, get your authentication token$curl \
-XPOST'https://api.spenza.com/api/v1/authenticate' \
-H'Content-Type: application/json' \
-d'{
"key": "api-key",
"secret": "api-secret"
}'
# Response
{
"message": "Authentication Success.",
"accessToken": "Your Auth Token for other APIs.",
"expiration": "token expiration time"
}
# Example Usage with Token
# Use the received token in subsequent API calls$curl \
-XGET'https://api.spenza.com/api/v1/sim-by-iccid' \
-H'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H'Content-Type: application/json' \
-d'{
"ICCID": "9999967890123456789"
}'
# Error Responses
# 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."
}]
}
# 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
# Request
# Purchase a plan using ICCID, productId and schedule info$curl \
-XPOST'https://api.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"
}'
# 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
# Request
# Cancel an active subscription$curl \
-XPOST'https://api.spenza.com/api/v1/cancel-subscription' \
-H'Authorization: Bearer YOUR_TOKEN' \
-H'Content-Type: application/json' \
-d'{
"ICCID": "9999967890123456789"
}'
# 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."
}]
}
# 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
# Request
# Retrieve the usage of a Sim$curl \
-XPOST'https://api.spenza.com/api/v1/telco/getUsage' \
-H'Authorization: Bearer YOUR_TOKEN' \
-H'Content-Type: application/json' \
-d'{
"subId": "1745863440782"
}'
# 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
# Request a new phone number for a SIM card$curl \
-XPOST'https://api.spenza.com/api/v1/renew-phone-number' \
-H'Authorization: Bearer YOUR_TOKEN' \
-H'Content-Type: application/json' \
-d'{
"ICCID": "9999967890123456789"
}'
# Response
{
"message": "Request placed successfully, new number will be assigned soon"
}
# Error Responses
# 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
# Request
# Validate ICCID format (no auth required)$curl \
-XPOST'https://api.spenza.com/api/v1/public/validate-iccid' \
-H'Content-Type: application/json' \
-d'{
"ICCID": "8901260853182965429"
}'
# Response
{
"isValid": true,
"message": "Valid ICCID."
}
Validate IMEI
# Request
# Validate IMEI format (no auth required)$curl \
-XPOST'https://api.spenza.com/api/v1/public/validate-imei' \
-H'Content-Type: application/json' \
-d'{
"IMEI": "356938035643809"
}'
