AfroTools Payroll API — African Payroll Compliance as an API

Overview

The AfroTools Payroll API exposes the same calculation engine that powers AfroTools' 14 free payroll calculators — as a REST API. Integrate African payroll compliance into your own app, HR platform, or fintech product without rebuilding the regulatory logic yourself.

Base URL:

https://afrotools.com/.netlify/functions/afrowork-api

All endpoints use POST with a JSON body. Responses are JSON. Authentication uses a Bearer token in the Authorization header.

Who uses this

🏦

Fintechs & Digital Banks

Net salary calculation for loan eligibility and salary advance products.

🧾

Accounting Firms

Payroll calculation for client portals without a full payroll system.

🖥️

HR & Payroll SaaS

Compliance logic for African countries you don't currently cover.

🛍️

Job Boards & Platforms

Real net salary display on job listings, across 54 countries.

Authentication

Every request requires a valid API key in the Authorization header:

curl

JavaScript

Python

curl -X POST \ https://afrotools.com/.netlify/functions/afrowork-api/v1/payroll/paye \ -H "Authorization: Bearer afro_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"country":"NG","gross_salary":450000,"frequency":"monthly"}'

// JavaScript (fetch) const response = await fetch( 'https://afrotools.com/.netlify/functions/afrowork-api/v1/payroll/paye', { method: 'POST', headers: { 'Authorization': 'Bearer afro_YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ country: 'NG', gross_salary: 450000, frequency: 'monthly' }) } ); const data = await response.json();

# Python (requests) import requests response = requests.post( 'https://afrotools.com/.netlify/functions/afrowork-api/v1/payroll/paye', headers={'Authorization': 'Bearer afro_YOUR_API_KEY'}, json={'country': 'NG', 'gross_salary': 450000, 'frequency': 'monthly'} ) data = response.json()

🔑

API keys start with afro_. Keep them secret — treat them like passwords. Never expose them client-side in production. They carry your rate limit quota.

Endpoints

All endpoints accept POST requests with a JSON body. The country code is always an ISO 3166-1 alpha-2 code (e.g. NG, KE, ZA).

POST /v1/payroll/paye PAYE income tax calculation

Calculate PAYE income tax for any African country. Uses the same engine as the AfroTools payslip calculators — current tax bands, personal reliefs, and deductible contributions.

Request body

Field	Type	Required	Description
country	string	required	ISO 3166-1 alpha-2 (e.g. `NG`, `KE`)
gross_salary	number	required	Gross amount in local currency
frequency	string	optional	`"monthly"` or `"annual"` (default: `"annual"`)
regime	string	optional	Tax regime, e.g. `"NTA_2026"` for Nigeria. Defaults to latest.

Response

Field	Type	Description
paye_annual	number	Annual PAYE tax
paye_monthly	number	Monthly PAYE tax
net_annual	number	Annual net pay after tax and deductions
net_monthly	number	Monthly net pay
effective_rate	number	Effective tax rate (0–1)
law_reference	string	Source law / authority

Example

Request

Response

{ "country": "NG", "gross_salary": 450000, "frequency": "monthly" }

{ "country": "NG", "gross_salary": 450000, "frequency": "monthly", "currency": "NGN", "tax_year": 2026, "regime": "NTA_2026", "paye_annual": 459000, "paye_monthly": 38250, "net_annual": 4941000, "net_monthly": 411750, "effective_rate": 0.085, "law_reference": "Federal Inland Revenue Service (FIRS)", "_meta": { "calls_remaining": 97, "resets": "2026-05-01" } }

POST /v1/payroll/minimum-wage Minimum wage lookup + compliance check

Returns the statutory minimum wage for a country and sector. Pass proposed_salary to get a compliance check (is_compliant, margin).

Request

Field	Required	Notes
country	required	ISO code
sector	optional	`general`, `domestic`, `farm`
proposed_salary	optional	Monthly salary to check compliance against

Example response

{ "country": "ZA", "sector": "general", "hourly": 28.79, "monthly": 4984, "currency": "ZAR", "effectiveDate": "2025-03-01", "proposed_salary": 5200, "is_compliant": true, "margin": 216, "margin_pct": 0.0433 }

POST /v1/payroll/payslip Full payslip: earnings + deductions + employer costs

Complete payslip calculation — PAYE, all social security contributions, employer costs, and net pay. Mirrors the AfroTools payslip generator output.

Example

Request

Response

{ "country": "GH", "employee": { "name": "Kofi Mensah", "id": "EMP-001" }, "period": { "month": 4, "year": 2026 }, "earnings": { "basic": 5000, "housing": 1000, "transport": 500 } }

{ "country": "GH", "period": "April 2026", "earnings": { "basic": 5000, "housing": 1000, "transport": 500, "gross": 6500 }, "deductions": { "paye": 812, "social_security": 358, "total": 1170 }, "employer_contributions": { "total": 877 }, "net_pay": 5330, "currency": "GHS" }

POST /v1/payroll/overtime Overtime pay calculation

Calculate overtime pay using country-specific multipliers (weekday, weekend, public holiday, night shift). Returns base hourly rate, multiplier, overtime amount, and the applicable law.

Request

Field	Required	Notes
country	required	ISO code
monthly_salary	required	Gross monthly salary
overtime_hours	required	Hours of overtime worked
day_type	optional	`weekday` \| `weekend` \| `public-holiday` \| `night-shift`

Example response

{ "country": "NG", "base_hourly_rate": 1152.07, "multiplier": 1.5, "multiplier_label": "Standard Overtime", "overtime_pay": 20737.26, "total_monthly_pay": 220737.26, "law_reference": "Labour Act Cap L1, Section 13" }

POST /v1/payroll/leave Statutory leave entitlements

Returns statutory leave entitlements for a country: annual, sick, maternity (with pay source), paternity, and public holidays.

Request

Response

{ "country": "TZ" }

{ "country": "TZ", "annualLeaveDays": 28, "sickLeaveDays": 126, "maternityLeaveDays": 84, "maternityPayPct": 100, "maternityPaySource": "employer", "paternityLeaveDays": 3, "publicHolidays": 16, "totalDaysOffPerYear": 44, "law": "Employment and Labour Relations Act 2004" }

POST /v1/payroll/staff-cost Total employer cost of an employee

Total cost to the employer: gross salary plus all employer-side contributions (pension, social security, levies). Includes a cost premium percentage.

Request

Field	Required
country	required
gross_salary	required
frequency	optional

Example response

{ "gross_monthly": 300000, "employer_contributions": 66000, "total_monthly_cost": 366000, "cost_premium_pct": 0.22, "currency": "NGN" }

Error Codes

All error responses return JSON with an error field describing what went wrong.

Status	Code	Meaning
200	OK	Request succeeded. Result in body.
400	Bad Request	Invalid JSON body, missing required field, or unsupported country.
401	Unauthorized	Missing or invalid API key. Check your Authorization header.
404	Not Found	Unknown route. Check the endpoint path.
405	Method Not Allowed	Use POST for all payroll endpoints.
429	Too Many Requests	Monthly call limit reached. Response includes `resets` date and upgrade link.
500	Server Error	Calculation error. Report via GitHub Issues.

# Example 401 response { "error": "Invalid or revoked API key", "docs": "https://afrotools.com/afrowork/api/" } # Example 429 response { "error": "Monthly rate limit exceeded", "plan": "free", "limit": 100, "calls_used": 100, "resets": "2026-05-01T00:00:00.000Z", "upgrade": "https://afrotools.com/afrowork/api/#pricing" }

Rate Limits

Rate limits are applied per API key, per calendar month (UTC). Limits reset on the 1st of each month at 00:00 UTC.

Plan	Monthly calls	Per-minute burst	Overage
Free	100	10 req/min	Blocked until next month
Starter	5,000	60 req/min	$0.01 / call
Growth	25,000	200 req/min	$0.01 / call
Pro	100,000	500 req/min	$0.01 / call
Enterprise	Unlimited	Custom	Dedicated SLA

Every response includes rate limit headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 97

Pricing

Start free. Upgrade when you scale. All plans cover all 54 African countries and all 7 endpoints.

Free

$0

/ month

100 calls

No SLA

Get key

Starter

$29

/ month

5,000 calls

Email support

Contact us

Growth ★

$99

/ month

25,000 calls

24hr support

Contact us

Pro

$299

/ month

100,000 calls

Priority + Slack

Contact us

Enterprise

Custom

Unlimited

Dedicated SLA

Contact us

Overage (Starter and above): $0.01 per call beyond monthly limit. Email api@afrotools.com to upgrade.

Changelog

Apr 2026

NEWv1 public launch — 7 endpoints, 54 countries.
NEWNigeria NTA 2026 tax bands live.
NEWKenya SHIF (Oct 2024), Affordable Housing Levy live.

Mar 2026

UPDATESouth Africa NMW updated to R28.79/hr (Mar 2025).
UPDATEGhana minimum wage updated to GHS 18.15/day.

Get Your API Key

Free tier: 100 calls/month. No credit card. Enter your email to generate a key instantly.

Email address

YOUR API KEY — copy it now, it won't be shown again

⚠ Store this securely. Treat it like a password — never commit to git or expose client-side.

Check Your Usage

Enter your API key to check your current month's usage.

African payroll complianceas an API.

Overview

Who uses this

Authentication

Endpoints

Request body

Response

Example

Example

Request

Example response

Example

Request

Example response

Request

Example response

Error Codes

Rate Limits

Pricing

Changelog

Get Your API Key

Check Your Usage

African payroll compliance
as an API.