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

Quick Start

# Calculate PIT for ₦5,000,000 annual income
curl -X POST https://staging.taxhq.ng/api/tax/calculate/pit \
  -H "Content-Type: application/json" \
  -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

Free Tier

- 1000 requests per day
- No authentication required
- All endpoints available

Response Format

- All responses are JSON
- Errors include message field
- Amounts are in Naira (₦)

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'])