API Documentation

Integrate TaxHQ tax calculations into your applications. Our API provides programmatic access to Nigerian tax calculations based on the Nigeria Tax Act 2025. All endpoints are free to use.

Base URL

https://staging.taxhq.ng/api

Authentication

TaxHQ API uses API Key + HMAC signature authentication for secure access. This prevents replay attacks and ensures request integrity.

Getting Your API Keys

Sign in to your TaxHQ account at taxhq.ng/profile
Navigate to the API Keys section in your dashboard
Click "Generate New API Key"
Copy and securely store your API Key and API Secret

Important: Your API Secret is only shown once. Store it securely—you cannot retrieve it later.

GET Requests (API Key Only)

For read-only GET requests, include only your API key in the header:

curl -X GET "https://staging.taxhq.ng/api/tax/reliefs?category=personal" \
  -H "X-API-Key: txhq_your_api_key_here"

POST/PUT/DELETE Requests (Signed)

Write operations require HMAC-SHA256 request signing to prevent tampering and replay attacks.

Required Headers

X-API-KeyYour API key (e.g., txhq_abc123...)

X-TimestampUnix timestamp in milliseconds (must be within 5 minutes of server time)

X-SignatureHMAC-SHA256 signature (hex-encoded)

Signature Calculation

// Signature = HMAC-SHA256(secret, payload)
// Payload format: timestamp.method.path.bodyHash

payload = "${timestamp}.${method}.${path}.${sha256(body)}"
signature = hmac_sha256(api_secret, payload)

JavaScript

import crypto from 'crypto';

async function signedRequest(method, path, body) {
  const timestamp = Date.now().toString();
  const bodyStr = body ? JSON.stringify(body) : '';
  const bodyHash = crypto
    .createHash('sha256')
    .update(bodyStr)
    .digest('hex');

  const payload = `${timestamp}.${method}.${path}.${bodyHash}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(payload)
    .digest('hex');

  return fetch(`${API_BASE}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
    body: bodyStr || undefined,
  });
}

// Usage
const result = await signedRequest(
  'POST',
  '/tax/calculate/pit',
  { grossIncome: 5000000 }
);

Python

import hmac
import hashlib
import json
import time
import requests

def signed_request(method, path, body=None):
    timestamp = str(int(time.time() * 1000))
    body_str = json.dumps(body) if body else ''
    body_hash = hashlib.sha256(
        body_str.encode()
    ).hexdigest()

    payload = f"{timestamp}.{method}.{path}.{body_hash}"
    signature = hmac.new(
        API_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return requests.request(
        method,
        f"{API_BASE}{path}",
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY,
            'X-Timestamp': timestamp,
            'X-Signature': signature,
        },
        json=body,
    )

# Usage
result = signed_request(
    'POST',
    '/tax/calculate/pit',
    {'grossIncome': 5000000}
)

IP Whitelisting (Enterprise)

Restrict API access to specific IP addresses for enhanced security. Configure allowed IPs in your dashboard or via API.

// Update allowed IPs via API
PATCH /api/user/api-keys
{
  "keyId": "your_key_id",
  "allowedIps": [
    "203.0.113.50",      // Single IP
    "192.168.1.0/24"     // CIDR range
  ]
}

Leave empty to allow requests from any IP address.

Key Rotation

Rotate your API keys periodically or if you suspect they've been compromised. The old key remains valid for 24 hours to allow graceful migration.

// Rotate API key
POST /api/user/api-keys/rotate
{
  "keyId": "your_existing_key_id"
}

// Response includes new key and secret
{
  "success": true,
  "data": {
    "id": "new_key_id",
    "key": "txhq_new_key...",
    "secret": "new_secret...",
    "expiresAt": "2027-01-15T00:00:00Z"
  },
  "message": "Old key will remain active for 24 hours"
}

Key Expiration

API keys expire after 1 year by default. You'll receive email notifications before expiration. Expired keys return a 401 INVALID_API_KEY error.

Security Best Practices

• Never expose API keys or secrets in client-side code or public repositories
• Use environment variables to store credentials
• Rotate keys periodically (every 90 days recommended)
• Enable IP whitelisting for production environments
• Monitor API usage and set up alerts for unusual activity
• Use separate keys for development and production

Quick Start

# Calculate PIT for ₦5,000,000 annual income (with authentication)
curl -X POST https://staging.taxhq.ng/api/tax/calculate/pit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"grossIncome": 5000000}'

Endpoints

POST/tax/validate-tin

Validate TIN

Validate Nigerian Tax Identification Number format

Parameters

tinstring (required) - TIN to validate (format: XXXXXXXX-XXXX)

typestring (optional) - Type: 'individual' or 'company'

Request Example

{
  "tin": "12345678-0001",
  "type": "company"
}

Response Example

{
  "valid": true,
  "tin": "12345678-0001",
  "type": "company",
  "format": "Valid format for company TIN",
  "checkDigitValid": true
}

POST/tax/calculate/pit

Calculate PIT

Calculate Personal Income Tax based on Nigeria Tax Act 2025

Parameters

grossIncomenumber (required) - Annual gross income in Naira

pensionContributionnumber (optional) - Annual pension contribution

nhfContributionnumber (optional) - NHF contribution

voluntaryPensionnumber (optional) - Voluntary pension savings

lifeInsurancenumber (optional) - Life insurance premium

Request Example

{
  "grossIncome": 5000000,
  "pensionContribution": 400000,
  "nhfContribution": 125000
}

Response Example

{
  "grossIncome": 5000000,
  "consolidatedRelief": 1200000,
  "pensionRelief": 400000,
  "nhfRelief": 125000,
  "totalReliefs": 1725000,
  "taxableIncome": 3275000,
  "taxPayable": 447000,
  "effectiveRate": 8.94,
  "netIncome": 4153000,
  "brackets": [
    { "bracket": "First ₦800,000", "rate": 0, "tax": 0 },
    { "bracket": "Next ₦2,000,000", "rate": 15, "tax": 300000 },
    { "bracket": "Remaining ₦475,000", "rate": 18, "tax": 85500 }
  ]
}

POST/tax/calculate/vat

Calculate VAT

Calculate Value Added Tax at 7.5%

Parameters

amountnumber (required) - Amount to calculate VAT on

inclusiveboolean (optional) - Whether amount includes VAT (default: false)

Request Example

{
  "amount": 100000,
  "inclusive": false
}

Response Example

{
  "amount": 100000,
  "vatRate": 7.5,
  "vatAmount": 7500,
  "totalWithVat": 107500,
  "priceWithoutVat": 100000
}

POST/tax/calculate/cit

Calculate CIT

Calculate Corporate Income Tax based on company size

Parameters

turnovernumber (required) - Annual turnover in Naira

profitnumber (required) - Taxable profit in Naira

Request Example

{
  "turnover": 80000000,
  "profit": 15000000
}

Response Example

{
  "turnover": 80000000,
  "profit": 15000000,
  "companySize": "medium",
  "citRate": 20,
  "citAmount": 3000000,
  "educationTax": 375000,
  "totalTax": 3375000,
  "effectiveRate": 22.5
}

GET/tax/reliefs

Get Tax Reliefs

Get list of all tax reliefs and exemptions

Parameters

categorystring (optional) - Filter by category (personal, business, investment, sector)

Request Example

GET /api/tax/reliefs?category=personal

Response Example

{
  "reliefs": [
    {
      "id": "cra",
      "name": "Consolidated Relief Allowance",
      "category": "personal",
      "description": "20% of gross income + ₦200,000",
      "eligibility": "All taxpayers",
      "maxAmount": null
    },
    ...
  ],
  "total": 50
}

GET/tax/deductions

Get Deductions

Get eligible deductions based on user profile

Parameters

incomenumber (required) - Annual income

hasChildrenboolean (optional) - Has dependent children

hasDisabilityboolean (optional) - Has disability

hasMortgageboolean (optional) - Paying mortgage

Request Example

GET /api/tax/deductions?income=5000000&hasChildren=true

Response Example

{
  "deductions": [
    {
      "name": "Child Education Allowance",
      "amount": 200000,
      "description": "Deduction for children's school fees"
    },
    ...
  ],
  "totalPotentialSavings": 450000
}

B2B Automation APIs

Enterprise-grade APIs for automating payroll, WHT, and VAT compliance workflows.

POST/b2b/payroll

Payroll API

Batch process PAYE calculations for multiple employees. Returns individual breakdowns and employer summary.

Available Actions

action: "calculate"

Calculate Batch

Process PAYE for multiple employees at once

action: "payslips"

Generate Payslips

Generate payslip data for employees

action: "paye-schedule"

PAYE Schedule

Generate FIRS-ready PAYE schedule for filing

Request Example

{
  "action": "calculate",
  "employer": {
    "name": "Your Company Ltd",
    "tin": "12345678-0001"
  },
  "employees": [
    {
      "id": "EMP001",
      "name": "John Doe",
      "grossSalary": 500000,
      "pensionContribution": 40000,
      "nhfContribution": 12500
    },
    {
      "id": "EMP002",
      "name": "Jane Smith",
      "grossSalary": 750000,
      "pensionContribution": 60000,
      "nhfContribution": 18750
    }
  ],
  "payPeriod": "2026-01"
}

Response Example

{
  "success": true,
  "data": {
    "employees": [
      {
        "id": "EMP001",
        "name": "John Doe",
        "grossSalary": 500000,
        "paye": 41250,
        "pension": 40000,
        "nhf": 12500,
        "netSalary": 406250
      },
      ...
    ],
    "summary": {
      "totalGross": 1250000,
      "totalPaye": 98750,
      "totalPension": 100000,
      "totalNhf": 31250,
      "totalNet": 1020000,
      "employeeCount": 2
    }
  }
}

POST/b2b/wht

WHT Automation

Automate Withholding Tax calculations, certificate generation, and FIRS schedule preparation

Available Actions

action: "process"

Process Payments

Generate WHT certificates for batch payments

action: "firs-schedule"

FIRS Schedule

Generate FIRS-ready WHT schedule for filing

action: "estimate"

Estimate WHT

Estimate WHT amounts for budgeting

action: "validate-tin"

Validate TIN

Validate vendor TIN format

Request Example

{
  "action": "process",
  "payer": {
    "name": "Your Company Ltd",
    "tin": "12345678-0001",
    "address": "Lagos, Nigeria"
  },
  "payments": [
    {
      "id": "PAY-001",
      "paymentDate": "2026-01-15",
      "vendor": {
        "name": "ABC Consultants",
        "tin": "87654321-0001"
      },
      "invoice": {
        "number": "INV-001",
        "description": "Consulting services"
      },
      "category": "professional_fees",
      "grossAmount": 500000,
      "isNonResident": false
    }
  ]
}

Response Example

{
  "success": true,
  "data": {
    "certificates": [...],
    "summary": {
      "totalGrossAmount": 500000,
      "totalWhtAmount": 50000,
      "totalNetAmount": 450000,
      "paymentCount": 1
    }
  }
}

WHT Categories & Rates

dividends: 10%interest: 10%rent: 10%professional_fees: 10%construction: 5%contracts: 5%

POST/b2b/vat

VAT Compliance

Validate VAT invoices, check claimability, and prepare VAT returns

Available Actions

action: "validate"

Validate Invoice

Validate a single VAT invoice for compliance

action: "validate-batch"

Batch Validation

Validate multiple invoices at once

action: "prepare-return"

Prepare Return

Prepare VAT return data for filing

action: "validate-tin"

Validate TIN

Validate supplier TIN and VAT registration

Request Example

{
  "action": "validate",
  "invoice": {
    "invoiceNumber": "INV-2026-001",
    "invoiceDate": "2026-01-15",
    "supplierName": "ABC Suppliers Ltd",
    "supplierTin": "12345678-0001",
    "buyerName": "Your Company Ltd",
    "lineItems": [
      {
        "description": "Office supplies",
        "quantity": 10,
        "unitPrice": 5000
      }
    ]
  }
}

Response Example

{
  "success": true,
  "data": {
    "isValid": true,
    "vatClaimable": true,
    "calculations": {
      "subtotal": 50000,
      "vatAmount": 3750,
      "total": 53750
    },
    "warnings": []
  }
}

VAT Information

Standard Rate: 7.5%

Exempt: Medical products, Basic food, Educational materials

Rate Limits & Usage

Public (No Key)

100

requests/hour

Free Tier

500

requests/hour

Starter

2,000

requests/hour

Business / Enterprise

10K - 100K

requests/hour

Rate Limit Headers

X-RateLimit-Limit - Your rate limit
X-RateLimit-Remaining - Requests left
X-RateLimit-Reset - Reset timestamp
Retry-After - Seconds until reset (429 only)

Response Format

• All responses are JSON
• Errors include error and code fields
• Amounts are in Naira (₦)
• Timestamps are ISO 8601 format

Error Handling

// Error Response Format
{
  "error": true,
  "message": "grossIncome is required",
  "code": "VALIDATION_ERROR"
}

// HTTP Status Codes
// 200 - Success
// 400 - Bad Request (invalid parameters)
// 429 - Rate Limit Exceeded
// 500 - Server Error

Code Examples

JavaScript / TypeScript

const response = await fetch(
  'https://staging.taxhq.ng/api/tax/calculate/pit',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grossIncome: 5000000,
      pensionContribution: 400000,
    }),
  }
);

const result = await response.json();
console.log(result.taxPayable);

Python

import requests

response = requests.post(
    'https://staging.taxhq.ng/api/tax/calculate/pit',
    json={
        'grossIncome': 5000000,
        'pensionContribution': 400000,
    }
)

result = response.json()
print(result['taxPayable'])

API Documentation

Integrate TaxHQ tax calculations into your applications. Our API provides programmatic access to Nigerian tax calculations based on the Nigeria Tax Act 2025. All endpoints are free to use.

Base URL

https://staging.taxhq.ng/api

Authentication

TaxHQ API uses API Key + HMAC signature authentication for secure access. This prevents replay attacks and ensures request integrity.

Getting Your API Keys

Sign in to your TaxHQ account at taxhq.ng/profile
Navigate to the API Keys section in your dashboard
Click "Generate New API Key"
Copy and securely store your API Key and API Secret

Important: Your API Secret is only shown once. Store it securely—you cannot retrieve it later.

GET Requests (API Key Only)

For read-only GET requests, include only your API key in the header:

curl -X GET "https://staging.taxhq.ng/api/tax/reliefs?category=personal" \
  -H "X-API-Key: txhq_your_api_key_here"

POST/PUT/DELETE Requests (Signed)

Write operations require HMAC-SHA256 request signing to prevent tampering and replay attacks.

Required Headers

X-API-KeyYour API key (e.g., txhq_abc123...)

X-TimestampUnix timestamp in milliseconds (must be within 5 minutes of server time)

X-SignatureHMAC-SHA256 signature (hex-encoded)

Signature Calculation

// Signature = HMAC-SHA256(secret, payload)
// Payload format: timestamp.method.path.bodyHash

payload = "${timestamp}.${method}.${path}.${sha256(body)}"
signature = hmac_sha256(api_secret, payload)

JavaScript

import crypto from 'crypto';

async function signedRequest(method, path, body) {
  const timestamp = Date.now().toString();
  const bodyStr = body ? JSON.stringify(body) : '';
  const bodyHash = crypto
    .createHash('sha256')
    .update(bodyStr)
    .digest('hex');

  const payload = `${timestamp}.${method}.${path}.${bodyHash}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(payload)
    .digest('hex');

  return fetch(`${API_BASE}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
    body: bodyStr || undefined,
  });
}

// Usage
const result = await signedRequest(
  'POST',
  '/tax/calculate/pit',
  { grossIncome: 5000000 }
);

Python

import hmac
import hashlib
import json
import time
import requests

def signed_request(method, path, body=None):
    timestamp = str(int(time.time() * 1000))
    body_str = json.dumps(body) if body else ''
    body_hash = hashlib.sha256(
        body_str.encode()
    ).hexdigest()

    payload = f"{timestamp}.{method}.{path}.{body_hash}"
    signature = hmac.new(
        API_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return requests.request(
        method,
        f"{API_BASE}{path}",
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY,
            'X-Timestamp': timestamp,
            'X-Signature': signature,
        },
        json=body,
    )

# Usage
result = signed_request(
    'POST',
    '/tax/calculate/pit',
    {'grossIncome': 5000000}
)

IP Whitelisting (Enterprise)

Restrict API access to specific IP addresses for enhanced security. Configure allowed IPs in your dashboard or via API.

// Update allowed IPs via API
PATCH /api/user/api-keys
{
  "keyId": "your_key_id",
  "allowedIps": [
    "203.0.113.50",      // Single IP
    "192.168.1.0/24"     // CIDR range
  ]
}

Leave empty to allow requests from any IP address.

Key Rotation

Rotate your API keys periodically or if you suspect they've been compromised. The old key remains valid for 24 hours to allow graceful migration.

// Rotate API key
POST /api/user/api-keys/rotate
{
  "keyId": "your_existing_key_id"
}

// Response includes new key and secret
{
  "success": true,
  "data": {
    "id": "new_key_id",
    "key": "txhq_new_key...",
    "secret": "new_secret...",
    "expiresAt": "2027-01-15T00:00:00Z"
  },
  "message": "Old key will remain active for 24 hours"
}

Key Expiration

API keys expire after 1 year by default. You'll receive email notifications before expiration. Expired keys return a 401 INVALID_API_KEY error.

Security Best Practices

• Never expose API keys or secrets in client-side code or public repositories
• Use environment variables to store credentials
• Rotate keys periodically (every 90 days recommended)
• Enable IP whitelisting for production environments
• Monitor API usage and set up alerts for unusual activity
• Use separate keys for development and production

Quick Start

# Calculate PIT for ₦5,000,000 annual income (with authentication)
curl -X POST https://staging.taxhq.ng/api/tax/calculate/pit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"grossIncome": 5000000}'

Endpoints

POST/tax/validate-tin

Validate TIN

Validate Nigerian Tax Identification Number format

Parameters

tinstring (required) - TIN to validate (format: XXXXXXXX-XXXX)

typestring (optional) - Type: 'individual' or 'company'

Request Example

{
  "tin": "12345678-0001",
  "type": "company"
}

Response Example

{
  "valid": true,
  "tin": "12345678-0001",
  "type": "company",
  "format": "Valid format for company TIN",
  "checkDigitValid": true
}

POST/tax/calculate/pit

Calculate PIT

Calculate Personal Income Tax based on Nigeria Tax Act 2025

Parameters

grossIncomenumber (required) - Annual gross income in Naira

pensionContributionnumber (optional) - Annual pension contribution

nhfContributionnumber (optional) - NHF contribution

voluntaryPensionnumber (optional) - Voluntary pension savings

lifeInsurancenumber (optional) - Life insurance premium

Request Example

{
  "grossIncome": 5000000,
  "pensionContribution": 400000,
  "nhfContribution": 125000
}

Response Example

{
  "grossIncome": 5000000,
  "consolidatedRelief": 1200000,
  "pensionRelief": 400000,
  "nhfRelief": 125000,
  "totalReliefs": 1725000,
  "taxableIncome": 3275000,
  "taxPayable": 447000,
  "effectiveRate": 8.94,
  "netIncome": 4153000,
  "brackets": [
    { "bracket": "First ₦800,000", "rate": 0, "tax": 0 },
    { "bracket": "Next ₦2,000,000", "rate": 15, "tax": 300000 },
    { "bracket": "Remaining ₦475,000", "rate": 18, "tax": 85500 }
  ]
}

POST/tax/calculate/vat

Calculate VAT

Calculate Value Added Tax at 7.5%

Parameters

amountnumber (required) - Amount to calculate VAT on

inclusiveboolean (optional) - Whether amount includes VAT (default: false)

Request Example

{
  "amount": 100000,
  "inclusive": false
}

Response Example

{
  "amount": 100000,
  "vatRate": 7.5,
  "vatAmount": 7500,
  "totalWithVat": 107500,
  "priceWithoutVat": 100000
}

POST/tax/calculate/cit

Calculate CIT

Calculate Corporate Income Tax based on company size

Parameters

turnovernumber (required) - Annual turnover in Naira

profitnumber (required) - Taxable profit in Naira

Request Example

{
  "turnover": 80000000,
  "profit": 15000000
}

Response Example

{
  "turnover": 80000000,
  "profit": 15000000,
  "companySize": "medium",
  "citRate": 20,
  "citAmount": 3000000,
  "educationTax": 375000,
  "totalTax": 3375000,
  "effectiveRate": 22.5
}

GET/tax/reliefs

Get Tax Reliefs

Get list of all tax reliefs and exemptions

Parameters

categorystring (optional) - Filter by category (personal, business, investment, sector)

Request Example

GET /api/tax/reliefs?category=personal

Response Example

{
  "reliefs": [
    {
      "id": "cra",
      "name": "Consolidated Relief Allowance",
      "category": "personal",
      "description": "20% of gross income + ₦200,000",
      "eligibility": "All taxpayers",
      "maxAmount": null
    },
    ...
  ],
  "total": 50
}

GET/tax/deductions

Get Deductions

Get eligible deductions based on user profile

Parameters

incomenumber (required) - Annual income

hasChildrenboolean (optional) - Has dependent children

hasDisabilityboolean (optional) - Has disability

hasMortgageboolean (optional) - Paying mortgage

Request Example

GET /api/tax/deductions?income=5000000&hasChildren=true

Response Example

{
  "deductions": [
    {
      "name": "Child Education Allowance",
      "amount": 200000,
      "description": "Deduction for children's school fees"
    },
    ...
  ],
  "totalPotentialSavings": 450000
}

B2B Automation APIs

Enterprise-grade APIs for automating payroll, WHT, and VAT compliance workflows.

POST/b2b/payroll

Payroll API

Batch process PAYE calculations for multiple employees. Returns individual breakdowns and employer summary.

Available Actions

action: "calculate"

Calculate Batch

Process PAYE for multiple employees at once

action: "payslips"

Generate Payslips

Generate payslip data for employees

action: "paye-schedule"

PAYE Schedule

Generate FIRS-ready PAYE schedule for filing

Request Example

{
  "action": "calculate",
  "employer": {
    "name": "Your Company Ltd",
    "tin": "12345678-0001"
  },
  "employees": [
    {
      "id": "EMP001",
      "name": "John Doe",
      "grossSalary": 500000,
      "pensionContribution": 40000,
      "nhfContribution": 12500
    },
    {
      "id": "EMP002",
      "name": "Jane Smith",
      "grossSalary": 750000,
      "pensionContribution": 60000,
      "nhfContribution": 18750
    }
  ],
  "payPeriod": "2026-01"
}

Response Example

{
  "success": true,
  "data": {
    "employees": [
      {
        "id": "EMP001",
        "name": "John Doe",
        "grossSalary": 500000,
        "paye": 41250,
        "pension": 40000,
        "nhf": 12500,
        "netSalary": 406250
      },
      ...
    ],
    "summary": {
      "totalGross": 1250000,
      "totalPaye": 98750,
      "totalPension": 100000,
      "totalNhf": 31250,
      "totalNet": 1020000,
      "employeeCount": 2
    }
  }
}

POST/b2b/wht

WHT Automation

Automate Withholding Tax calculations, certificate generation, and FIRS schedule preparation

Available Actions

action: "process"

Process Payments

Generate WHT certificates for batch payments

action: "firs-schedule"

FIRS Schedule

Generate FIRS-ready WHT schedule for filing

action: "estimate"

Estimate WHT

Estimate WHT amounts for budgeting

action: "validate-tin"

Validate TIN

Validate vendor TIN format

Request Example

{
  "action": "process",
  "payer": {
    "name": "Your Company Ltd",
    "tin": "12345678-0001",
    "address": "Lagos, Nigeria"
  },
  "payments": [
    {
      "id": "PAY-001",
      "paymentDate": "2026-01-15",
      "vendor": {
        "name": "ABC Consultants",
        "tin": "87654321-0001"
      },
      "invoice": {
        "number": "INV-001",
        "description": "Consulting services"
      },
      "category": "professional_fees",
      "grossAmount": 500000,
      "isNonResident": false
    }
  ]
}

Response Example

{
  "success": true,
  "data": {
    "certificates": [...],
    "summary": {
      "totalGrossAmount": 500000,
      "totalWhtAmount": 50000,
      "totalNetAmount": 450000,
      "paymentCount": 1
    }
  }
}

WHT Categories & Rates

dividends: 10%interest: 10%rent: 10%professional_fees: 10%construction: 5%contracts: 5%

POST/b2b/vat

VAT Compliance

Validate VAT invoices, check claimability, and prepare VAT returns

Available Actions

action: "validate"

Validate Invoice

Validate a single VAT invoice for compliance

action: "validate-batch"

Batch Validation

Validate multiple invoices at once

action: "prepare-return"

Prepare Return

Prepare VAT return data for filing

action: "validate-tin"

Validate TIN

Validate supplier TIN and VAT registration

Request Example

{
  "action": "validate",
  "invoice": {
    "invoiceNumber": "INV-2026-001",
    "invoiceDate": "2026-01-15",
    "supplierName": "ABC Suppliers Ltd",
    "supplierTin": "12345678-0001",
    "buyerName": "Your Company Ltd",
    "lineItems": [
      {
        "description": "Office supplies",
        "quantity": 10,
        "unitPrice": 5000
      }
    ]
  }
}

Response Example

{
  "success": true,
  "data": {
    "isValid": true,
    "vatClaimable": true,
    "calculations": {
      "subtotal": 50000,
      "vatAmount": 3750,
      "total": 53750
    },
    "warnings": []
  }
}

VAT Information

Standard Rate: 7.5%

Exempt: Medical products, Basic food, Educational materials

Rate Limits & Usage

Public (No Key)

100

requests/hour

Free Tier

500

requests/hour

Starter

2,000

requests/hour

Business / Enterprise

10K - 100K

requests/hour

Rate Limit Headers

X-RateLimit-Limit - Your rate limit
X-RateLimit-Remaining - Requests left
X-RateLimit-Reset - Reset timestamp
Retry-After - Seconds until reset (429 only)

Response Format

• All responses are JSON
• Errors include error and code fields
• Amounts are in Naira (₦)
• Timestamps are ISO 8601 format

Error Handling

// Error Response Format
{
  "error": true,
  "message": "grossIncome is required",
  "code": "VALIDATION_ERROR"
}

// HTTP Status Codes
// 200 - Success
// 400 - Bad Request (invalid parameters)
// 429 - Rate Limit Exceeded
// 500 - Server Error

Code Examples

JavaScript / TypeScript

const response = await fetch(
  'https://staging.taxhq.ng/api/tax/calculate/pit',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grossIncome: 5000000,
      pensionContribution: 400000,
    }),
  }
);

const result = await response.json();
console.log(result.taxPayable);

Python

import requests

response = requests.post(
    'https://staging.taxhq.ng/api/tax/calculate/pit',
    json={
        'grossIncome': 5000000,
        'pensionContribution': 400000,
    }
)

result = response.json()
print(result['taxPayable'])