AfroTools API Documentation — African Tax, FX & Salary Data for Developers

Overview

The AfroTools API provides programmatic access to African financial data — tax rates, exchange rates, salary benchmarks, and PAYE calculations covering all 54 African countries.

Built for fintechs, HR platforms, payroll systems, and developer tools. Start with the free tier (100 requests/day) — no credit card required.

Base URL: https://afrotools.com/api/
All endpoints return JSON with Content-Type: application/json.

Authentication

Include your API key in every request using one of these methods:

# Header (recommended)
x-api-key: afro_live_xxxxxxxxxxxxx

# Or query parameter
?api_key=afro_live_xxxxxxxxxxxxx

Example with cURL

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

Example with JavaScript

const res = await fetch('https://afrotools.com/api/tax-rates?country=NG', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await res.json();

Example with Python

import requests

data = requests.get(
    "https://afrotools.com/api/tax-rates",
    params={"country": "NG"},
    headers={"x-api-key": "YOUR_API_KEY"}
).json()

Test keys: Keys starting with afro_test_ bypass rate limits and return live data. Use for development.

Rate Limits

Tier	Daily Limit	Monthly Limit
Free	100	3,000
Pro (coming soon)	10,000	300,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Limits reset at midnight UTC daily.

Error Codes

All errors return a JSON body with an error field:

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

Status	Code	Meaning
400	MISSING_REQUIRED_FIELD	A required parameter is missing
401	INVALID_API_KEY	Missing or invalid API key
404	INVALID_COUNTRY	Country code not recognized
429	RATE_LIMIT_EXCEEDED	Daily rate limit exceeded
500	INTERNAL_ERROR	Server error — try again

Tax Calculate (PAYE)

The most powerful endpoint — compute African PAYE without building your own engine. Supports gross-to-net and net-to-gross calculations for 53 countries.

POST /api/v1/tax

Calculate income tax for any supported African country.

Request Body

Field	Type	Required	Description
`country`	string	Required	ISO 3166-1 alpha-2 code (e.g., NG, KE, ZA)
`grossAnnual`	number	*	Annual gross salary in local currency
`grossMonthly`	number	*	Monthly gross salary (alternative)
`netAnnual`	number	*	Net salary for reverse calculation
`regime`	string	Optional	Tax regime (e.g., NTA_2026 for Nigeria)
`pension`	boolean	Optional	Include pension deduction (default: true)

* Provide one of grossAnnual, grossMonthly, netAnnual, or netMonthly.

Example Request

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

Example Response

{
  "status": "success",
  "input": { "country": "NG", "grossAnnual": 7200000, "regime": "NTA_2026" },
  "deductions": {
    "pension": 576000,
    "nhf": 180000,
    "totalDeductions": 1773600
  },
  "tax": {
    "taxableIncome": 6444000,
    "netTax": 1017600,
    "bands": [...]
  },
  "result": {
    "netAnnual": 5426400,
    "netMonthly": 452200,
    "effectiveRate": "14.13%"
  }
}

GET: List Supported Countries

GET /api/v1/tax?country=NG

Get country tax info, supported regimes, and available options.

curl "https://afrotools.com/api/v1/tax" \
  -H "x-api-key: YOUR_API_KEY"

Tax Rates (Reference Data)

Static reference data — PAYE bands, VAT rates, and tax authority info for all African countries.

GET /api/tax-rates

Get tax rate data for one or all African countries.

Parameters

Parameter	Type	Required	Description
`country`	string	Optional	ISO alpha-2 code. Omit for all countries.
`type`	string	Optional	`paye` or `vat` to filter.

Example Request

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

Example Response

{
  "country": "NG",
  "country_name": "Nigeria",
  "currency": "NGN",
  "tax_authority": "FIRS",
  "paye": {
    "regimes": ["PITA_2025", "NTA_2026"],
    "year": "2026",
    "source": "Federal Inland Revenue Service (FIRS)"
  },
  "vat": {
    "standard_rate": 0.075,
    "currency": "NGN"
  }
}

FX Rates

Exchange rates for African currencies with historical data support.

GET /api/fx-rates

Get current or historical exchange rates.

Parameters

Parameter	Type	Required	Description
`base`	string	Optional	Base currency (e.g., USD). Returns all African pairs.
`target`	string	Optional	Target currency (e.g., NGN).
`days`	number	Optional	Historical days (e.g., 30 for 30-day history). Requires base + target.

Example Request

curl "https://afrotools.com/api/fx-rates?base=USD&target=NGN" \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "base": "USD",
  "target": "NGN",
  "rate": 1580.50,
  "source": "CBN",
  "updated_at": "2026-03-19T08:00:00Z",
  "change_24h": -0.32
}

Salary Benchmarks

Salary benchmark data aggregated from AfroTools users.

GET /api/salary-benchmarks

Get salary benchmarks for a specific country.

Parameters

Parameter	Type	Required	Description
`country`	string	Required	ISO alpha-2 code (e.g., NG, KE, ZA)
`period`	string	Optional	`monthly` (default) or `annual`

Example Response

{
  "country": "NG",
  "currency": "NGN",
  "period": "monthly",
  "sample_size": 1250,
  "gross": { "median": 450000, "p25": 250000, "p75": 800000 },
  "net": { "median": 375000, "p25": 220000, "p75": 680000 },
  "effective_tax_rate": 12.5
}

Countries

Reference data for all 54 African countries including currencies, regions, and available tools.

GET /api/countries

List all African countries or get detail for one.

Parameters

Parameter	Type	Required	Description
`code`	string	Optional	ISO alpha-2 code for single-country detail.

Example Response (single country)

{
  "code": "NG",
  "name": "Nigeria",
  "currency": "NGN",
  "currency_symbol": "\u20a6",
  "region": "West Africa",
  "population": 230000000,
  "tools_available": ["paye", "vat", "fx"]
}

Get Your API Key

Save this key now. It will not be shown in full again.