Overview
- Validate Invoice
- Validate IRN
- Sign Invoice
- Download Invoice
- Report Invoice Payment
- Update Invoice
Overview
The FIRS E-Invoice API enables businesses to validate, sign, transmit, and manage electronic invoices in compliance with Nigerian tax regulations. This API integrates with the Federal Inland Revenue Service (FIRS) e-invoicing system.
Base URL:
- Authentication:
- Every request must include:
🔐 Authentication
Required Headers (All Endpoints)
Header
Type
Description
🧾 Invoice APIs
1. Validate Invoice
Validate an invoice payload before signing or transmission.
POST:
Request Body Example
Json
{
“irn”: “{{test-irn}}”,
“issue_date”: “2025-01-09”,
“due_date”: “2025-01-10”,
“issue_time”: “12:46:25”,
“invoice_type_code”: “381”,
“payment_status”: “PENDING”,
“note”: “fail”,
“document_currency_code”: “NGN”,
“order_reference”: “Abc0008”,
“payment_terms_note”: “”,
“tax_currency_code”: “NGN”,
“tax_total”: [
{
“tax_amount”: 3999739938.78,
“tax_subtotal”: [
{
“taxable_amount”: 5000000000,
“tax_amount”: 3999739938.78,
“tax_category”: {
“id”: “STANDARD_VAT”,
“percent”: 0.075
}
}
]
}
],
“invoice_line”: [
{
“invoiced_quantity”: 100000,
“line_extension_amount”: 50000000,
“isic_code”: “01”,
“service_category”: “product”,
“item”: {
“name”: “building”,
“description”: “building”,
“sellers_item_identification”: “item_1762421710391_42l3h4nij”
},
“price”: {
“price_amount”: 500,
“base_quantity”: 100000,
“price_unit”: “NGN per 1”
}
}
],
“legal_monetary_total”: {
“line_extension_amount”: 10000,
“tax_exclusive_amount”: 10000,
“tax_inclusive_amount”: 5000000000,
“payable_amount”: 5000000000
},
“accounting_customer_party”: {
“party_name”: “kenneth”,
“tin”: “73046528-7756”,
“email”: “[email protected]”,
“telephone”: “+2349078989989”,
“postal_address”: {
“street_name”: “plaza 10, kingsword.”,
“city_name”: “ikeja”,
“postal_zone”: “100001”,
“country”: “NG”
}
}
}
2. Validate IRN
Validate an invoice reference number (IRN).
Request Body
3. Sign Invoice
Digitally sign an invoice after validation.
POST:
Request body follows the same structure as the Validation payload.
4. Download Invoice
Download an invoice PDF/XML from Jureb.
Returns:
- PDF or XML document (depending on setup)
5. Report Invoice Payment
Send payment settlement details to Jureb/FIRS.
POST:
Request Body Example
Json
{
“irn”: “{{test-irn}}”,
“payment_status”: “PAID”,
“beneficiary_tin”: “{{test-tin}}”,
“base_amount”: 150000,
“currency”: “NGN”,
“item_description”: “IT consulting services for Feb 2024”,
“total_amount”: 165000,
“transaction_date”: “2024-02-19”,
“vat_calculated”: 15000,
“vat_rate”: 10,
“vat_status”: “STANDARD_VAT”,
“other_taxes”: “0”
}
6. Update Invoice
Update the payment status or reference of an invoice.
POST:
Request Body Example
🚚 Transmission APIs
7. Transmit Invoice
Push a validated & signed invoice to FIRS.
Returns:
- Transmission status (queued, successful, or failed)
8. Acknowledge Invoice
Acknowledge receipt from FIRS after transmission.
📚 Resources APIs
These endpoints return static reference data required for building invoices.
9. Get HS Codes GET:
GET:
Returns:
- List of HS codes for goods categorization
10. Get ISIC Codes
Returns:
- Approved service classification codes
11. Get Taxes
GET:
Returns:
- Approved service classification codes
- VAT category list
- VAT percentages
- Tax rules
12. Get Invoice Types
Returns:
- FIRS-compliant invoice types (e.g., Standard, Credit Note, Debit Note)