External API v1
A RESTful API for partners, retailers, repair shops, and manufacturers to integrate with TechSosten services programmatically.
https://your-domain.com/api/v1Authentication
All API requests require an API key sent via the x-api-key header.
x-api-key: tks_<your-64-char-hex-key>Getting an API Key
- Log into your TechSosten dashboard as an organization admin.
- Navigate to Settings → API Keys.
- Click Generate New Key, give it a name, and select the required permissions.
- Save the key immediately — it will not be shown again.
Permission Scopes
| Permission | Description |
|---|---|
devices:write | Register and renew devices (charged) |
repairs:read | View repair orders |
repairs:write | Create and update repair orders |
trade-in:read | View trade-in requests |
trade-in:write | Submit trade-in requests (charged if assessed) |
protection:read | View protection plans |
Rate Limiting
Rate limits protect the API from excessive traffic and ensure fair usage.
- Default: 60 requests per minute per API key.
- Configured per key at creation time.
- Exceeded: Returns a
429 Too Many Requestsresponse. - Reset: Rate limit resets every 60 seconds.
Pagination
List endpoints support pagination via query parameters.
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| page | integer | 1 | — | Page number to retrieve |
| limit | integer | 20 | 100 | Number of items per page |
Response Format
{
"data": [
"..."
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
}
}Endpoints
All available API endpoints organized by resource.
Devices
Register, list, renew, and delete device registrations.
/api/v1/devicesList/search devices registered to your organization.Query Parameters
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| status | string | — | — | Filter by device status (e.g. Active, Expired) |
| search | string | — | — | Search by brand, model, serial number, or IMEI |
| page | integer | 1 | — | Page number |
| limit | integer | 20 | 100 | Items per page |
Response
{
"data": [
{
"_id": "...",
"device": {
"brand": "Samsung",
"model": "Galaxy S24",
"serialNumber": "SN123456789"
},
"status": "Active"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
}
}/api/v1/devicesRegister a new device. Registration is always free.Request Body
{
"device": {
"type": "Smartphone",
"brand": "Samsung",
"model": "Galaxy S24",
"serialNumber": "SN123456789",
"purchaseDate": "2025-01-15T00:00:00.000Z",
"purchasePrice": 500000
}
}Device registration is free — no charge is generated.
/api/v1/devices/:idGet a single device by ID.Response
{
"_id": "...",
"device": {
"brand": "Apple",
"model": "iPhone 15"
},
"status": "Active"
}/api/v1/devices/:idRenew or update a device.Request Body
{
"device": {
"purchaseDate": "2026-01-15T00:00:00.000Z"
}
}Renewal is free. Charges come from buying capability (modules, insurance) for a device.
/api/v1/devices/:idDelete a device registration.Repairs
Create, list, update, and delete repair orders (free, no charge).
/api/v1/repairsList repair orders.Query Parameters
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| serialNumber | string | — | — | Filter by device serial number |
| status | string | — | — | Filter by status (e.g. Pending, In Progress, Completed) |
| page | integer | 1 | — | Page number |
| limit | integer | 20 | 100 | Items per page |
/api/v1/repairsCreate a new repair order.Request Body
{
"client": "64a1b2c3d4e5f6a7b8c9d0e1",
"device": {
"type": "Smartphone",
"brand": "Google",
"model": "Pixel 9",
"serialNumber": "SN987654321"
},
"issue": "Screen cracked - display not working",
"serviceType": "repair",
"deliveryType": "drop-off"
}/api/v1/repairs/:idGet a specific repair by ID./api/v1/repairs/:idUpdate repair details (status, cost, notes)./api/v1/repairs/:idDelete a repair order.Trade-In
Submit and manage trade-in requests.
/api/v1/trade-inList trade-in requests.Query Parameters
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| status | string | — | — | Filter by status (e.g. Pending Review, Assessed, Completed) |
| page | integer | 1 | — | Page number |
| limit | integer | 20 | 100 | Items per page |
/api/v1/trade-inSubmit a trade-in request.Request Body
{
"userId": "64a1b2c3d4e5f6a7b8c9d0e1",
"deviceId": "64a1b2c3d4e5f6a7b8c9d0e2",
"reportedCondition": {
"physicalState": "Good",
"functional": "Fully Functional",
"hasOriginalBox": true,
"hasCharger": true
}
}A charge is created only after the super admin sets an assessed value.
Protection Plans
Register and manage device protection plans.
/api/v1/protectionLook up protection plans by device.Query Parameters
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| serialNumber | string | — | — | Filter by device serial number |
| imei | string | — | — | Filter by device IMEI |
| status | string | — | — | Filter by status (e.g. Active, Expired) |
| page | integer | 1 | — | Page number |
| limit | integer | 20 | 100 | Items per page |
/api/v1/protectionRegister a new protection plan.Request Body
{
"client": "64a1b2c3d4e5f6a7b8c9d0e1",
"device": {
"type": "Smartphone",
"brand": "Apple",
"model": "iPhone 15",
"serialNumber": "SN555666777"
},
"insuranceProvider": "achor",
"billingCycle": "annual",
"declaredValue": 500000,
"coverageStart": "2025-02-01T00:00:00.000Z",
"coverageEnd": "2026-02-01T00:00:00.000Z"
}/api/v1/protection/:idGet a protection plan by ID./api/v1/protection/:idUpdate a protection plan./api/v1/protection/:idDelete a protection plan.Payments
List pending charges and pay via wallet.
/api/v1/paymentsList pending and paid charges for your organization.Response
{
"summary": {
"pendingCount": 2,
"totalPendingNGN": 1881.25,
"currency": "NGN"
},
"pending": [
{
"_id": "...",
"moduleId": "tech-support",
"cost": 1612.5,
"status": "pending",
"expiresAt": "..."
}
],
"paid": []
}/api/v1/paymentsPay a pending charge using your wallet balance.Request Body
{
"chargeId": "<charge-id-from-list>"
}Returns a 402 Payment Required if wallet balance is insufficient. Returns 410 Gone if the 24-hour window expired.
Billing & Payments
Device registration is free. Charges come from buying capability per device (modules, insurance, API usage) and from admin-quoted repairs or trade-in. Catalogue prices are stored pre-VAT; 7.5% VAT is added at checkout.
What costs what
| Operation | How cost is determined |
|---|---|
POST /api/v1/devices | Free — registering a device, including bulk fleet registration, never creates a charge |
Module checkout | Module price + 7.5% VAT, per device, per cycle — e.g. Tech Support at ₦1,500 + ₦112.50 VAT = ₦1,612.50 per month |
POST /api/v1/trade-in | Super-admin assessed value — charged only once the admin sets a value |
API resources | Per successful setup or call — ₦500 per setup (tech_support, device_diagnostics, geo_fencing), ₦230 per call (device_verification, device_certification), settled from the organisation wallet |
Device registration is free
There are no plans and no seat licences. Registration — including bulk fleet registration — costs nothing; you only pay when you buy a capability for a device.
Paying Charges
- List pending charges:
GET /api/v1/payments - Pay via wallet:
POST /api/v1/paymentswith{"chargeId": "<charge-id>"} - Top up your wallet from the dashboard Billing page if balance is low.
A 402 Payment Required response means insufficient funds. A 410 Gone response means the 24-hour window expired.
Chargeable Response Example
When you buy a capability for a device, the response includes a payment notice:
{
"_id": "...",
"device": {
"brand": "Samsung",
"model": "Galaxy S24"
},
"moduleInfo": {
"moduleId": "tech-support",
"cycle": "monthly",
"price": 1500,
"vatAmount": 112.5,
"priceWithVat": 1612.5
},
"payment": {
"status": "pending",
"amount": 1612.5,
"currency": "NGN",
"dueBy": "2026-06-16T15:00:00.000Z",
"message": "Payment of 1,612.50 NGN is due within 24 hours. Pay via POST /api/v1/payments"
}
}Error Codes
All errors follow a consistent JSON format.
{
"error": "Human-readable error message"
}| Status | Meaning | Description |
|---|---|---|
| 400 | Bad Request | Missing or invalid parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 402 | Payment Required | Insufficient wallet balance |
| 403 | Forbidden | API key does not have the required permission |
| 404 | Not Found | Resource not found |
| 410 | Gone | Payment window expired (24 hours) |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
Code Examples
Get started quickly with these examples in your preferred language.
cURL
Register a device
curl -X POST https://your-domain.com/api/v1/devices \
-H "x-api-key: tks_<your-key>" \
-H "Content-Type: application/json" \
-d '{
"device": {
"brand": "Samsung",
"model": "Galaxy S24",
"serialNumber": "SN123456789",
"purchasePrice": 500000
}
}'List pending charges
curl https://your-domain.com/api/v1/payments \
-H "x-api-key: tks_<your-key>"Pay a charge
curl -X POST https://your-domain.com/api/v1/payments \
-H "x-api-key: tks_<your-key>" \
-H "Content-Type: application/json" \
-d '{"chargeId": "<charge-id-from-list>"}'JavaScript / Fetch
const API_KEY = 'tks_<your-key>';
const BASE = 'https://your-domain.com/api/v1';
async function registerDevice(device) {
const res = await fetch(`${BASE}/devices`, {
method: 'POST',
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ device }),
});
return res.json();
}
async function listCharges() {
const res = await fetch(`${BASE}/payments`, {
headers: { 'x-api-key': API_KEY },
});
return res.json();
}
async function payCharge(chargeId) {
const res = await fetch(`${BASE}/payments`, {
method: 'POST',
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ chargeId }),
});
return res.json();
}
// Example: Register a device
registerDevice({
brand: 'Apple',
model: 'iPhone 15',
purchasePrice: 750000,
}).then(console.log);Python
import requests
API_KEY = 'tks_<your-key>'
BASE = 'https://your-domain.com/api/v1'
headers = {'x-api-key': API_KEY}
# Register a device
response = requests.post(
f'{BASE}/devices',
headers={**headers, 'Content-Type': 'application/json'},
json={
'device': {
'brand': 'Apple',
'model': 'iPhone 15',
'purchasePrice': 750000
}
}
)
print(response.json())
# Submit a trade-in request
response = requests.post(
f'{BASE}/trade-in',
headers={**headers, 'Content-Type': 'application/json'},
json={
'userId': '64a1b2c3d4e5f6a7b8c9d0e1',
'deviceId': '64a1b2c3d4e5f6a7b8c9d0e2',
'reportedCondition': {
'physicalState': 'Good',
'functional': 'Fully Functional'
}
}
)
print(response.json())