Start in sandbox. Move to a reviewed API pilot.

Quickstart

Use the demo sandbox key below for deterministic development responses. Replace it with a dashboard key when your route needs authenticated production access.

curl -X POST "https://afrotools.com/api/v1/tax/paye" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","grossMonthly":500000}'

Expected result: 200 OK with status, sandbox, and result.netMonthly.

Authentication

Send API keys with the x-api-key header. Query-string keys are accepted for quick testing, but headers are recommended for production.

# Header, recommended
x-api-key: afro_live_xxxxxxxxxxxxx

# Query parameter, quick testing only
?api_key=afro_live_xxxxxxxxxxxxx

Rate limits

Where a route exposes rate-limit headers, they use X-RateLimit-Limit and X-RateLimit-Remaining. Daily limits reset at midnight UTC.

Endpoint catalog

SalaryPadi tool catalog

This server-to-server endpoint publishes schema version 1.0.0. Every tool is explicitly classified as api, widget, or link. PAYE and FX are API integrations. Other career tools remain link integrations until a matching calculation or widget contract is both implemented and tested.

curl "https://afrotools.com/api/v1/catalog/tools?product=salarypadi&category=career" \
  -H "x-api-key: $SALARYPADI_API_KEY"

A representative tool record inside the response:

{
  "id": "ng-paye",
  "integrationMode": "api",
  "canonicalUrl": "https://afrotools.com/nigeria/ng-salary-tax",
  "countries": ["NG"],
  "api": { "method": "POST", "path": "/api/v1/tax/paye" },
  "inputSchema": "https://afrotools.com/api/schemas/v1/paye-request.schema.json",
  "outputSchema": "https://afrotools.com/api/schemas/v1/paye-response.schema.json",
  "rulesVersion": "NG-PAYE:PITA_2025+NTA_2026",
  "lastVerified": "2026-07-11"
}

Successful responses include standard ETag, the exact application validator in X-AfroTools-Catalog-ETag, Cache-Control, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Scope. Prefer the AfroTools validator and replay its exact value in both X-AfroTools-If-None-Match and standard If-None-Match; the application header takes precedence when an intermediary consumes or normalizes the standard header. Retain the last-known-good catalog on 304 Not Modified. The full schema is published at /api/schemas/v1/tool-catalog-response.schema.json.

PAYE calculate

Calculate gross-to-net or net-to-gross PAYE scenarios. Provide one salary input.

Every successful response follows the published PAYE response schema. Each tax.bands[] item includes canonical label, rate, and amount fields. Production rows retain from, to, and taxInBand as v1 compatibility fields. Production metadata includes _meta.sandbox: false and a non-empty _meta.dataPolicy.

curl -X POST "https://afrotools.com/api/v1/tax/paye" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","grossMonthly":500000}'

Tax rates

Read PAYE and VAT reference data. Use country for a single market and type to filter to paye or vat. Production responses include sandbox: false and a non-empty data_policy; deterministic sandbox responses identify themselves with sandbox: true.

curl "https://afrotools.com/api/v1/tax/rates?country=NG" \
  -H "x-api-key: afro_test_demo123456789"

VAT calculate

Add VAT to an exclusive amount or extract VAT from an inclusive amount.

curl -X POST "https://afrotools.com/api/v1/vat/calculate" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","amount":1000,"operation":"add"}'

FX rates

Read current rates, single pairs, base conversions, and stored historical pairs where available.

curl "https://afrotools.com/api/v1/fx/rates?base=USD&target=NGN"

Fuel prices

Read petrol, diesel, and LPG prices where source coverage is available. Results include timestamps and source metadata.

curl "https://afrotools.com/api/v1/fuel/prices?country=NG"

Central-bank rates

Read policy rates, inflation reference data, central-bank names, and source fields by country or region.

curl "https://afrotools.com/api/v1/rates/central-bank?country=NG"

Countries

Read country names, currencies, regions, population reference values, and available API products.

curl "https://afrotools.com/api/v1/countries?code=NG" \
  -H "x-api-key: afro_test_demo123456789"

Status and health

The status route returns the public API contract. The v1 health route returns category freshness and source metadata.

curl "https://afrotools.com/api/status"

curl "https://afrotools.com/api/v1/health"

Error format

Errors return JSON with an error field and, where available, a stable code.

{
  "error": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}

Production path

Use sandbox keys for deterministic examples, Free API for dashboard-key testing, and API Growth or API Pro when a real product needs higher limits or support. Enterprise/custom is available for negotiated data scope, request limits, billing, and implementation review.