e-Invoicing API Specification

The Taxable E-Invoicing API lets a business create invoices, submit them to the Nigeria Revenue Service (NRS) for clearance, and receive back an Invoice Reference Number (IRN) that makes each invoice independently verifiable. Around that core clearance flow, the API provides customer management, invoice lifecycle actions (send, pay, void, credit and debit notes), PDF and signed-document retrieval, purchase (input-side) invoice recording, and a per-period VAT ledger that feeds VAT return prefill.

The API serves two audiences with two distinct authentication families:

• Partner API (/partner/v1/*) is for third-party integrators. Authenticated with an API key in the x-api-key header. Each key maps to exactly one business.
• First-party API is used by Taxable's own invoicing application and developer console. Authenticated with a platform-issued JWT bearer token, scoped to a single business per request.

There is also one deliberately public, unauthenticated endpoint, GET /nrs/verify/{irn}, so that anyone holding an invoice can verify its authenticity without platform credentials.

1. Sign in. Authentication is passwordless. Enter your email address and the console sends a magic link. The same link both registers a new developer account and signs in an existing one, so there is no separate signup form. The link is verified server-side before any session cookie is set.

2. Select your business and check NRS enrolment. The console home page shows a business selector and the NRS enrolment status of the selected business. NRS enrolment is a precondition for issuing invoices that clear. If the business is not yet enrolled, complete enrolment before attempting your first issue call.

3. Create an API key. Create, list, and revoke Partner API keys for the selected business. Existing keys are always displayed masked.

4. Register a webhook. Register your outbound webhook endpoint URL and choose the event types you want to receive. The signing secret is also shown once, at registration. Store it alongside your API key; you will use it to verify webhook signatures. The webhooks page includes a delivery log with one-click replay of failed deliveries.

5. Make your first call. Passing an invoice payload to POST /partner/v1/invoices creates the invoice; by default it is issued immediately (use ?issue=false to create a draft only).

curl -X POST "https://dev-api.taxable.ng/partner/v1/invoices" \
     -H "x-api-key: $TAXABLE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "customer": {
             "name": "Eko Allied Manufacturing Ltd",
             "tin": "01234567-0001",
             "email": "accounts@ekoallied.ng",
             "address": "14 Creek Road, Apapa, Lagos"
         },
         "issueDate": "2026-07-13",
         "dueDate": "2026-08-12",
         "currency": "NGN",
         "lineItems": [
             {
                 "description": "Industrial packaging film — 500kg roll",
                 "quantity": 4,
                 "unitPrice": 185000.00,
                 "vatRate": 7.5
             },
             {
                 "description": "Delivery and handling, Apapa to Ikeja",
                 "quantity": 1,
                 "unitPrice": 45000.00,
                 "vatRate": 7.5
             }
         ]
     }'

{
    "success": true,
    "data": {
        "id": "inv_01J9ZQ4T8RVXW2M5KD73PA6QNH",
        "invoiceNumber": "INV-2026-0147",
        "status": "ISSUED",
        "irn": "IRN-1784297456123",
        "customer": { "name": "Eko Allied Manufacturing Ltd", "tin": "01234567-0001" },
        "currency": "NGN",
        "subtotal": 785000.00,
        "vatAmount": 58875.00,
        "total": 843875.00,
        "issueDate": "2026-07-13",
        "dueDate": "2026-08-12"
    }
}

Note the sandbox-shaped IRN (IRN-<epoch-ms>). In production the IRN follows the NRS format; see the IRN format appendix.

6. Watch it in the audit log. The console's activity page shows recent Partner API calls made with the selected business's keys: method, path, status, latency, and request ID. See Audit log for exactly what is, and is never, recorded.

7. Optional: bulk import. For high-volume backfills, upload an invoice CSV, watch rows clear via live polling against the batch-status endpoint, and download a per-row result CSV showing success or failure for every line.

Partner API: every /partner/v1/* route requires the key. Keys are attached to an API gateway usage plan, so rate limiting and the monthly quota are enforced at the gateway, before a request reaches application code.

curl "https://api.taxable.ng/partner/v1/invoices?status=ISSUED&limit=20" \
    -H "x-api-key: $TAXABLE_API_KEY"

First-party calls carry a platform-issued bearer JWT. The authenticated user must hold the OWNER or ACCOUNTANT role on the target business, otherwise the request is rejected with 403.

• Base URLs: production https://api.taxable.ng, sandbox https://dev-api.taxable.ng. Integrate and certify against sandbox first.
• Content type: request and response bodies are JSON; send Content-Type: application/json. The exception is binary document endpoints (invoice PDF).
• Business scoping: Partner API calls are scoped automatically, because the API key identifies the business.
• Monetary units: all monetary values in this API — invoice amounts, tax summaries, and VAT ledger figures — are expressed in document-currency major units, that is naira with decimal kobo (e.g. 185000.00). No minor-unit conversion is applied at any layer.

Rate limits (Partner API), enforced at the API gateway via a usage plan, per key:

Every Partner API endpoint can return 429 Too Many Requests. Treat 429 as retryable with exponential backoff and jitter.

{
    "success": false,
    "error": {
        "type": "rate_limited",
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Request rate limit exceeded. Retry with backoff."
    }
}

Customers. Customers are the counterparties on your invoices. Creating them as first-class records lets you reference them by ID and keeps TIN and contact data consistent across invoices.

Invoices: create, issue, lifecycle.

{
    "success": true,
    "data": {
        "id": "inv_01J9ZQ4T8RVXW2M5KD73PA6QNH",
        "invoiceNumber": "INV-2026-0147",
        "status": "ISSUED",
        "irn": "IRN-1784297456123",
        "clearedAt": "2026-07-13T10:02:44Z"
    }
}

Documents and clearance status.

Purchases (input-side invoices).

VAT ledger. Every cleared invoice and recorded purchase feeds a per-business, per-period VAT ledger, which is the source for VAT return prefill. Periods use YYYY-MM. All ledger amounts are in naira, consistent with the invoice endpoints.

{
    "success": true,
    "data": {
        "period": "2026-06",
        "output": {
            "standardRated": 550500000.00,
            "zeroRated": 0.00,
            "exempt": 0.00,
            "totalVat": 41287500.00,
            "entryCount": 214
        },
        "input": {
            "vatableValue": 124000000.00,
            "inputVatPaid": 9300000.00,
            "entryCount": 37
        },
        "adjustments": {
            "netAdjustment": 0.00,
            "entryCount": 0
        }
    }
}

Resources.

Verify the authenticity of an invoice by its IRN. Anyone holding an invoice — a consumer checking a receipt, an auditor sampling a ledger, a counterparty's accounts team — can confirm that the IRN is genuine and corresponds to a cleared invoice, without needing platform credentials.

curl "https://api.taxable.ng/nrs/verify/INV0147-A1B2C3D4-20260713"

This is a trust-and-transparency feature of the platform: the value of an IRN comes precisely from the fact that its validity can be checked by anyone, independently of the parties to the transaction.

It covers the following capability families:

The following event types are available for subscription:

Signature verification. Each webhook endpoint has a signing secret, shown once at registration. Every delivery is signed with this secret; verify the signature before trusting a payload, and reject deliveries that fail verification.

Delivery, retries, and replay. The console's webhooks page includes a delivery log for your endpoint. Failed deliveries can be replayed with one click, so a transient outage on your side never means silently lost events. Design your handler to be idempotent: between retries and manual replay, the same event can legitimately arrive more than once.

Two practical notes: the log covers key-authenticated Partner API calls, so it is the audit trail for your integration's traffic specifically; and the request ID shown is the same ID you can capture from the API response, making the log directly correlatable with your own application logs when raising a support issue.

Sandbox IRNs are locally generated and exist so the full clearance flow can be exercised end-to-end without touching the live regulator gateway. Production IRNs follow the NRS reference-number format and are verifiable by anyone via GET /nrs/verify/{irn}. The ServiceID segment shown above is illustrative; each accredited provider is assigned its own.

On 429, back off exponentially with jitter. If your integration's steady-state volume approaches the monthly quota, contact Taxable about your usage plan before you hit it; the quota is a gateway-enforced hard stop.