API Reference

The primary integration surface is invoice submission. This page documents the endpoint in full; for everything else — listing invoices, checking status, managing customers — the same organisation-scoped data model your dashboard uses applies.

Submit an invoice

POST/api/v1/invoices

Creates and queues an invoice for NRS clearance. Authenticate with x-api-key — see Authentication. The organisation is resolved from the key, so there's no organisation id in the URL and nothing to tamper with.

Request body

{
  "invoiceNumber": "INV-0001",
  "invoiceDate": "2026-08-16",
  "currency": "NGN",
  "invoiceKind": "B2B",
  "invoiceTypeCode": "380",
  "customerName": "Acme Traders Ltd",
  "customerTin": "12345678-0001",
  "customerAddress": "14 Marina Road, Lagos",
  "customerEmail": "billing@acmetraders.example",
  "lineItems": [
    {
      "description": "Consulting services — August 2026",
      "quantity": 1,
      "unitPrice": 150000,
      "taxRate": 7.5,
      "itemType": "SERVICES",
      "isicCode": "6202",
      "serviceCategory": "IT consultancy"
    }
  ]
}

201 response

{
  "id": "3f7a2b10-9c4d-4e2a-8b5f-1d0e6a2c9f31",
  "invoiceNumber": "INV-0001",
  "status": "pending_clearance",
  "invoiceKind": "B2B",
  "createdAt": "2026-08-16T09:12:00Z"
}

The response carries an HTTP success status regardless of what NRS eventually decides — clearance is asynchronous. A gateway rejection is not an API error; see Troubleshooting for the difference.

invoiceTypeCode values

Code	Meaning
380	Commercial invoice
381	Credit note
383	Debit note

Rate limits

Applied per client IP. Exceeding one returns 429.

Scope	Limit	Window
`All endpoints`	60 requests	60 seconds
`/api/auth/*`	5 requests	60 seconds

NRS applies its own separate limit. If NRS throttles a submission, it comes back as a gateway rejection and can be resubmitted unchanged after a few minutes.

Other endpoints

Bulk and read endpoints

For submitting many invoices at once, use CSV/Excel bulk upload from the dashboard rather than looping individual API calls — see Integration Guides. Listing and status-check endpoints mirror this same organisation-scoped invoice model; reach out via Support if you need their exact paths before they're published here.