External API v1

External API v1

A RESTful API for partners, retailers, repair shops, and manufacturers to integrate with TechSosten services programmatically.

Base URL
https://your-domain.com/api/v1

Authentication

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

  1. Log into your TechSosten dashboard as an organization admin.
  2. Navigate to Settings → API Keys.
  3. Click Generate New Key, give it a name, and select the required permissions.
  4. Save the key immediately — it will not be shown again.

Permission Scopes

PermissionDescription
devices:writeRegister and renew devices (charged)
repairs:readView repair orders
repairs:writeCreate and update repair orders
trade-in:readView trade-in requests
trade-in:writeSubmit trade-in requests (charged if assessed)
protection:readView 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 Requests response.
  • Reset: Rate limit resets every 60 seconds.

Pagination

List endpoints support pagination via query parameters.

ParameterTypeDefaultMaxDescription
pageinteger1—Page number to retrieve
limitinteger20100Number of items per page

Response Format

json
{
  "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.

GET/api/v1/devicesList/search devices registered to your organization.
Query Parameters
ParameterTypeDefaultMaxDescription
statusstring——Filter by device status (e.g. Active, Expired)
searchstring——Search by brand, model, serial number, or IMEI
pageinteger1—Page number
limitinteger20100Items per page
Response
json
{
  "data": [
    {
      "_id": "...",
      "device": {
        "brand": "Samsung",
        "model": "Galaxy S24",
        "serialNumber": "SN123456789"
      },
      "status": "Active"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
POST/api/v1/devicesRegister a new device. Registration is always free.
Auth: devices:write
Request Body
json
{
  "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.

GET/api/v1/devices/:idGet a single device by ID.
Response
json
{
  "_id": "...",
  "device": {
    "brand": "Apple",
    "model": "iPhone 15"
  },
  "status": "Active"
}
PATCH/api/v1/devices/:idRenew or update a device.
Auth: devices:write
Request Body
json
{
  "device": {
    "purchaseDate": "2026-01-15T00:00:00.000Z"
  }
}

Renewal is free. Charges come from buying capability (modules, insurance) for a device.

DELETE/api/v1/devices/:idDelete a device registration.
Auth: devices:write

Repairs

Create, list, update, and delete repair orders (free, no charge).

GET/api/v1/repairsList repair orders.
Auth: repairs:read
Query Parameters
ParameterTypeDefaultMaxDescription
serialNumberstring——Filter by device serial number
statusstring——Filter by status (e.g. Pending, In Progress, Completed)
pageinteger1—Page number
limitinteger20100Items per page
POST/api/v1/repairsCreate a new repair order.
Auth: repairs:write
Request Body
json
{
  "client": "64a1b2c3d4e5f6a7b8c9d0e1",
  "device": {
    "type": "Smartphone",
    "brand": "Google",
    "model": "Pixel 9",
    "serialNumber": "SN987654321"
  },
  "issue": "Screen cracked - display not working",
  "serviceType": "repair",
  "deliveryType": "drop-off"
}
GET/api/v1/repairs/:idGet a specific repair by ID.
Auth: repairs:read
PATCH/api/v1/repairs/:idUpdate repair details (status, cost, notes).
Auth: repairs:write
DELETE/api/v1/repairs/:idDelete a repair order.
Auth: repairs:write

Trade-In

Submit and manage trade-in requests.

GET/api/v1/trade-inList trade-in requests.
Auth: trade-in:read
Query Parameters
ParameterTypeDefaultMaxDescription
statusstring——Filter by status (e.g. Pending Review, Assessed, Completed)
pageinteger1—Page number
limitinteger20100Items per page
POST/api/v1/trade-inSubmit a trade-in request.
Auth: trade-in:write
Request Body
json
{
  "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.

GET/api/v1/protectionLook up protection plans by device.
Auth: protection:read
Query Parameters
ParameterTypeDefaultMaxDescription
serialNumberstring——Filter by device serial number
imeistring——Filter by device IMEI
statusstring——Filter by status (e.g. Active, Expired)
pageinteger1—Page number
limitinteger20100Items per page
POST/api/v1/protectionRegister a new protection plan.
Auth: protection:read
Request Body
json
{
  "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"
}
GET/api/v1/protection/:idGet a protection plan by ID.
Auth: protection:read
PATCH/api/v1/protection/:idUpdate a protection plan.
Auth: protection:read
DELETE/api/v1/protection/:idDelete a protection plan.
Auth: protection:read

Payments

List pending charges and pay via wallet.

GET/api/v1/paymentsList pending and paid charges for your organization.
Response
json
{
  "summary": {
    "pendingCount": 2,
    "totalPendingNGN": 1881.25,
    "currency": "NGN"
  },
  "pending": [
    {
      "_id": "...",
      "moduleId": "tech-support",
      "cost": 1612.5,
      "status": "pending",
      "expiresAt": "..."
    }
  ],
  "paid": []
}
POST/api/v1/paymentsPay a pending charge using your wallet balance.
Request Body
json
{
  "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

OperationHow cost is determined
POST /api/v1/devicesFree — registering a device, including bulk fleet registration, never creates a charge
Module checkoutModule 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-inSuper-admin assessed value — charged only once the admin sets a value
API resourcesPer 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

  1. List pending charges: GET /api/v1/payments
  2. Pay via wallet: POST /api/v1/payments with {"chargeId": "<charge-id>"}
  3. 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:

json
{
  "_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.

json
{
  "error": "Human-readable error message"
}
StatusMeaningDescription
400Bad RequestMissing or invalid parameters
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient wallet balance
403ForbiddenAPI key does not have the required permission
404Not FoundResource not found
410GonePayment window expired (24 hours)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

Code Examples

Get started quickly with these examples in your preferred language.

cURL

Register a device

bash
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

bash
curl https://your-domain.com/api/v1/payments \
  -H "x-api-key: tks_<your-key>"

Pay a charge

bash
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

javascript
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

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())