Registers a new organisation and creates the first user account (the owner). The user receives the finance role with is_owner = true.

Request Body

Response: 201 Created

{
  "data": {
    "token": "1|abcdefghijklmnopqrstuvwxyz",
    "user": {
      "id": "uuid", "name": "Adaeze Okonkwo",
      "email": "adaeze@acme.ng", "role": "finance"
    },
    "organization": { "id": "uuid", "name": "Acme Nigeria Ltd" }
  }
}

Authenticates a user and returns a bearer token.

Request Body

Response: 200 OK

{
  "data": {
    "token": "2|abcdefghijklmnopqrstuvwxyz",
    "user": {
      "id": "uuid", "name": "Adaeze Okonkwo",
      "email": "adaeze@acme.ng",
      "role": "finance", "is_owner": true
    }
  }
}

Revokes the current bearer token. The token becomes invalid immediately.

Response: 200 OK

{ "data": { "message": "Logged out successfully." } }

Returns a paginated list of invoices for the authenticated organisation.

Query Parameters

Response: 200 OK

{
  "data": [
    {
      "id": "uuid",
      "irn": "INV001-2741A890-20260701",
      "invoice_number": "INV001",
      "issue_date": "2026-07-01",
      "status": "signed",
      "currency_code": "NGN",
      "total_amount": 150000.00,
      "vat_amount": 19565.22
    }
  ],
  "meta": { "total": 42, "per_page": 15, "current_page": 1, "last_page": 3 }
}

Creates a new invoice in draft status. Supplier party details are taken from the organisation's taxpayer profile. The IRN is built and validated server-side. Per-line amounts and totals are calculated server-side.

Request Body

Supplier details (name, TIN, email, address) are never sent in this request; they are always taken from the organisation's own taxpayer profile, set up once during onboarding. Every field in the table above that has an NRS name is sent to NRS in the signing request, so nothing you send here is dropped on the way.

Rules NRS enforces

NRS checks these when the invoice is validated and signed. The API rejects what it can straight away with a 422 and a message naming the field. Everything else comes back from NRS as the invoice's failure_reason.

Example Request

{
  "invoice_number": "INV001",
  "invoice_type_code": "381",
  "invoice_kind": "B2B",
  "issue_date": "2026-07-01",
  "issue_time": "14:30:00",
  "due_date": "2026-07-31",
  "tax_point_date": "2026-07-01",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "payment_means_code": "30",
  "payment_terms_note": "Net 30",
  "buyer_reference": "PO-2026-014",
  "order_reference": "PO-2026-014",
  "accounting_cost": "500",
  "billing_reference_irn": "REF001-2741A890-20260601",
  "billing_reference_date": "2026-06-01",
  "buyer": {
    "party_name": "Sample Buyer Enterprises Ltd",
    "tin": "98765432-0001",
    "email": "accounts@samplebuyer.example",
    "telephone": "08012345678",
    "street_name": "10 Admiralty Way",
    "city_name": "Lekki",
    "state_code": "NG-LA",
    "lga_code": "NG-LA-EOS",
    "country_code": "NGA",
    "postal_zone": "106104"
  },
  "bill": {
    "party_name": "Sample Buyer Finance Department",
    "tin": "98765432-0001",
    "email": "finance@samplebuyer.example",
    "street_name": "3 Bourdillon Road",
    "city_name": "Ikoyi",
    "state_code": "NG-LA",
    "lga_code": "NG-LA-EOS",
    "postal_zone": "101233"
  },
  "lines": [
    {
      "item_type": "services",
      "item_name": "Invota e-invoicing platform - annual subscription",
      "product_category": "Software Services",
      "isic_code": "6202",
      "service_category": "Computer consultancy and computer facilities management activities",
      "invoiced_quantity": 1,
      "price_unit": "EA",
      "price_amount": 250000,
      "tax_category_id": "STANDARD_VAT"
    }
  ]
}

Response: 201 Created

{
  "id": "uuid",
  "irn": "INV001-2741A890-20260701",
  "invoice_number": "INV001",
  "status": "draft",
  "created_at": "2026-07-01T09:00:00+00:00"
}

Returns the full details of a single invoice including all line items and party details.

Updates a draft invoice. Only allowed when status is draft. Only the account owner (is_owner = true) may edit an invoice. If the invoice number or issue date changes, the IRN is rebuilt and re-validated server-side.

Request Body

Send only the fields you want to change, using the same field names and rules as POST /invoices. To remove the payee, billing contact or delivery address, send null for it (for example "bill": null). A failed invoice that was rejected before NRS accepted it (it has no validated date) can also be edited and submitted again. Any other invoice that has left draft cannot be changed.

Soft-deletes a draft invoice. Only allowed when status is draft. Only the account owner may delete. Deleted invoices are not permanently removed from the database.

Creates up to 100 invoices in a single request, for quick imports. This dashboard bulk route accepts a shorter set of fields than a single invoice does: invoice_number, issue_date, due_date, document_currency_code, payment_means_code, note, buyer (party_name, email, telephone), and for each line item_name, item_type, invoiced_quantity, price_amount, price_unit, tax_category_id, tax_rate_percent, hsn_code, isic_code and discount_rate. For the full set of NRS fields (document references, payee, billing contact, delivery address and so on), create invoices one at a time with POST /invoices, or use the enterprise bulk route POST /b2b/invoices/bulk, which accepts the full body for every invoice.

Request Body

{ "invoices": [ { ... }, { ... } ] }

Response: 207 Multi-Status

Returns a result for each submitted invoice: success or the specific validation error for that item.

Submits a draft invoice to NRS for validation and signing. Dispatches a background job that first validates the invoice against NRS, then signs it and generates the QR code. The invoice status moves from draft through validated to signed if both steps succeed.

If NRS rejects the invoice, its status becomes failed and the reason NRS gave is saved in failure_reason, which you can read with GET /invoices/{id}. A rejection that retrying cannot fix (for example a missing TIN or a badly formed reference) fails straight away. A temporary problem on the NRS side, such as a timeout or a "try again later" reply, is retried automatically up to three times before the invoice is marked failed. Fix the cause, then submit the invoice again.

A B2C invoice is complete once it is signed. It is registered with NRS at that point and is not transmitted to a buyer system.

Response: 202 Accepted

{ "data": { "message": "Invoice submitted. Processing in background." } }

Polls NRS to confirm the current status of an invoice by its IRN. Use this to check whether a submitted invoice has been signed or to surface any NRS-side issue.

Response: 200 OK

{ "data": { "irn": "...", "status": "signed", "nrs_message": "..." } }

Transmits a signed invoice to the NRS exchange network so the buyer's system can receive it. Only available once the invoice status is signed. Runs as a background job.

Response: 202 Accepted

{ "data": { "message": "Invoice queued for transmission." } }

Updates the payment status of an invoice. When status is set to PAID or PARTIAL, the system automatically queues a VAT post-payment report to NRS and sends a receipt email to the buyer.

Request Body

The report to NRS only goes out once the invoice has been signed. If you mark an invoice paid before it is signed, the report is sent automatically as soon as signing completes.

Streams the invoice as a downloadable PDF. Includes the invoice header, supplier and buyer details, line items, tax totals, the IRN, and the QR code image.

Response

Content-Type: application/pdf. File is streamed as a download.

Returns a time-limited pre-signed URL to the QR code image in file storage. Only available once the invoice is signed.

Response: 200 OK

{ "data": { "url": "https://storage.invota.ng/qr-codes/org-id/irn.png?token=..." } }

Queues an email to the buyer containing invoice details and a PDF attachment.

Response: 202 Accepted

{ "data": { "message": "Email queued for delivery." } }

Returns a paginated list of customers for the authenticated organisation.

Query Parameters

Creates a new customer record.

Request Body

Returns the full details of a single customer.

Updates a customer record. All fields are optional.

Deletes a customer record.

Returns a paginated list of items for the authenticated organisation.

Query Parameters

Creates a new item.

Request Body

Returns the full details of a single item.

Updates an item record.

Deletes an item record.

Returns aggregate invoice statistics over a given date range.

Query Parameters

Response: 200 OK

{
  "data": {
    "total_invoices": 127,
    "total_value": 4500000.00,
    "total_vat": 586956.52,
    "by_status": {
      "draft": 5, "signed": 12,
      "acknowledged": 98, "reported": 12, "failed": 0
    }
  }
}

Returns VAT post-payment report records for the authenticated organisation.

Query Parameters

Exports a list of invoices as a CSV file for the given date range and optional status filter.

Query Parameters

Response

Content-Type: text/csv. File is streamed as a download.

Submits a single invoice through the B2B API. It takes exactly the same request body as POST /invoices (Section 3), with the same fields and the same rules, so every NRS field is available to you: document references, payee, billing contact, delivery address, discounts and charges, and the rest. The invoice is saved, then a background job validates and signs it with NRS. The response comes back straight away with the IRN, which you use to poll for progress.

Two differences from the dashboard route: the supplier is always your own business profile, and a B2B or B2G invoice must have a buyer with a TIN (or incorporation_number) and a full postal address. A B2C invoice may leave the buyer out. Invoices created with a sandbox key are marked sandbox and are never sent to NRS; a production key sends them for real.

Response: 202 Accepted

{
  "id": "uuid",
  "irn": "INV001-2741A890-20260701",
  "invoice_number": "INV001",
  "status": "draft",
  "payable_amount": "268750.00",
  "qr_url": null,
  "pdf_url": null
}

qr_url and pdf_url are empty at this point. The QR code is filled in once the invoice is signed; poll GET /b2b/invoices/{irn} to get it.

Errors

Returns the current status of an invoice by its IRN. Poll this after submitting to track progress.

Response: 200 OK

{
  "id": "uuid",
  "irn": "INV001-2741A890-20260701",
  "invoice_number": "INV001",
  "invoice_kind": "B2B",
  "status": "signed",
  "payment_status": "PENDING",
  "payable_amount": "268750.00",
  "tax_amount": "18750.00",
  "issue_date": "2026-07-01",
  "due_date": "2026-07-31",
  "validated_at": "2026-07-01T09:00:03+00:00",
  "signed_at": "2026-07-01T09:00:06+00:00",
  "transmitted_at": null,
  "acknowledged_at": null,
  "failure_reason": null,
  "qr_url": "https://storage.invota.ng/qr-codes/...",
  "pdf_url": null
}

status moves through draft, validated, signed, transmitting, transmitted, acknowledged and reported, or ends at failed. When it is failed, failure_reason holds the reason NRS gave, in plain text. Fix the cause and submit a new invoice. qr_url is a temporary link that lasts 30 minutes, so request it again when you need it.

Tells us a payment status from your own system, for example when your ERP or till marks an invoice paid. Once the invoice has been signed, a PAID or PARTIAL update sends the VAT report to NRS and emails the buyer a receipt, the same as marking it paid in the dashboard.

Request Body

Response: 200 OK

{
  "id": "uuid",
  "irn": "INV001-2741A890-20260701",
  "payment_status": "PAID",
  "partial_amount_paid": null,
  "payment_confirmed_at": "2026-07-05T10:12:00+00:00",
  "nrs_vat_report_queued": true
}

Submits up to 50 invoices in a single request. Every invoice takes the full request body, the same as a single POST /b2b/invoices. Each invoice is checked on its own: one with a mistake is reported against its position in your list and the others are still created, and the response is 207 Multi-Status. The account-level errors listed under POST /b2b/invoices (credentials, KYC, billing, supplier profile) reject the whole request, and so does a missing or empty list or more than 50 invoices.

Request Body

{ "invoices": [ { ... }, { ... } ] }

Response: 207 Multi-Status

{
  "created": [
    { "index": 0, "id": "uuid", "irn": "INV001-2741A890-20260701", "status": "draft" }
  ],
  "errors": [
    {
      "index": 1,
      "invoice_number": "INV002",
      "error": "Validation failed.",
      "errors": { "payee.tin": ["The payee.tin field is required when payee is present."] }
    },
    { "index": 2, "irn": "INV003-2741A890-20260701", "error": "Duplicate IRN" }
  ],
  "summary": { "total": 3, "created": 1, "failed": 2 }
}

Returns the current active credential for the authenticated B2B client (key ID and creation date). The actual key and secret values are not returned after initial provisioning.

Rotates the B2B API credentials. The old key is deactivated immediately. The new key and secret are returned once only.

Response: 200 OK

{
  "data": {
    "api_key": "new-key-shown-once",
    "api_secret": "new-secret-shown-once"
  }
}

Overview stats for the enterprise dashboard home page: submission counts by outcome, the 10 most recent invoices, and the organisation's current billing state.

Response: 200 OK

{
  "stats": {
    "total_submitted": 812, "validated_count": 790,
    "failed_count": 6, "pending_count": 16
  },
  "billing": {
    "mode": "prepaid",
    "outstanding_balance": 0,
    "credit_limit_ngn": 500000,
    "credits_balance": 340,
    "plan_slug": "enterprise",
    "per_invoice_rate_ngn": 50.00,
    "currency": "NGN",
    "available_packs": [
      { "id": "100", "credits": 100, "price_ngn": 5000 },
      { "id": "500", "credits": 500, "price_ngn": 22500 }
    ]
  },
  "recent_invoices": [ { "id": "uuid", "irn": "...", "status": "signed", "..." : "..." } ],
  "webhook_callback_url": "https://erp.example.com/hooks/invota"
}

Returns metadata for the active API credential (environment, created/rotated/revoked timestamps). The key and secret values are never returned here, only at the moment they are created or rotated. Credentials are issued automatically once KYC is approved; if none exist yet, credential is null.

Rotates the active credential within its current environment. The old key stops working immediately. Same one-time-reveal rule as /b2b/credentials/rotate above.

Switches between sandbox and production. The environment is encoded in the key prefix itself, so switching issues a brand new key pair rather than relabeling the old one: every credential in the other environment is revoked at the same time, so nothing from the previous environment keeps working afterwards.

Request Body

Switches how invoice submissions are billed: payg (Pay As You Go, a running balance invoiced per submission) or prepaid (a credits balance that decreases per submission, topped up manually). Switching to Prepaid is blocked while an outstanding PAYG balance is unpaid.

Request Body

Starts a Paystack payment, either clearing an outstanding PAYG balance (purpose: "balance") or buying a prepaid credit pack (purpose: "credits", with a pack_id from the packs listed in GET /enterprise/summary). Returns a Paystack checkout URL to redirect the user to.

Request Body

Response: 200 OK

{ "authorization_url": "https://checkout.paystack.com/...", "reference": "ent_...", "amount_ngn": 5000 }

Verifies a Paystack transaction reference after the user returns from checkout and applies it, clearing the balance or crediting the purchased pack onto credits_balance. Safe to call more than once for the same reference; an already-applied payment is reported back without being applied twice.

Request Body

Sets the URL that receives NRS transmission events for this organisation's invoices (see Section 9). Must be https:// in production.

Sends a single synthetic test event to the saved webhook URL right away, so the user can confirm it's reachable before relying on it. This is a one-off reachability check, not a real event; it is not retried and has no connection to the fire-and-forget delivery used for actual invoice events.

Response: 200 OK / 422

{ "verified": true, "reason": "ok", "status_code": 200 }

This endpoint receives event notifications from NRS. It is registered with NRS as the callback URL for all transmission events. Always returns HTTP 200 to acknowledge receipt. Duplicate events are detected using SHA-256 hash checks and ignored automatically.

Returns the cached list for the given type.

Available Types

Response: 200 OK

{
  "data": [
    { "code": "380", "name": "Credit Note",         "resource_type": "invoice_types" },
    { "code": "381", "name": "Commercial Invoice",  "resource_type": "invoice_types" }
  ]
}

Returns the authenticated organisation's overall KYC status plus the state of each individual required document.

Response: 200 OK

{
  "kyc_status": "pending",
  "documents": [
    {
      "type": "cac_certificate",
      "label": "CAC Certificate of Incorporation",
      "required": true,
      "status": "approved",
      "rejection_reason": null,
      "submitted_at": "2026-07-01T09:00:00Z",
      "reviewed_at": "2026-07-02T11:00:00Z"
    },
    {
      "type": "directors_id",
      "label": "Director's Government ID",
      "required": true,
      "status": "pending",
      "rejection_reason": null,
      "submitted_at": "2026-07-01T09:05:00Z",
      "reviewed_at": null
    }
  ]
}

Overall Status Values

Document Types

Uploads one document for one type. Re-submitting a type that is still pending or was rejected replaces it; an already approved document cannot be overwritten by re-uploading. Send as multipart/form-data, not JSON.

Request Body (multipart/form-data)

Response: 201 Created

{
  "message": "Document submitted for review.",
  "document_type": "cac_certificate",
  "status": "pending",
  "submitted_at": "2026-07-01T09:00:00Z"
}

Returns the authenticated organisation's current subscription and payment method state.

Response: 200 OK

{
  "subscription": {
    "plan_slug": "growth",
    "plan_name": "Growth",
    "status": "active",
    "billing_type": "monthly",
    "monthly_fee_ngn": 15000,
    "invoice_limit": 200,
    "invoices_used": 47,
    "cycle_start_at": "2026-07-01T00:00:00Z",
    "cycle_end_at": "2026-08-01T00:00:00Z",
    "next_renewal_at": "2026-08-01T00:00:00Z",
    "outstanding_balance": 0,
    "gateway": "paystack",
    "has_payment_method": true,
    "card_last4": "4081",
    "card_type": "visa",
    "card_expiry": "09/28",
    "features": ["Up to 200 invoices/month", "Email support"],
    "trial_days": 0,
    "is_popular": true
  }
}

Returns a paginated list of payment events (charges, renewals, failures) for the authenticated organisation, newest first.

Query Parameters

Downloads the full payment history as a CSV file.

Response

Content-Type: text/csv. File is streamed as a download.

Starts a Paystack payment to activate or renew a subscription plan. Returns a checkout URL to redirect the user to. Consent note: activating a plan this way saves the card used and authorises automatic renewal charges each billing cycle until the plan is changed or cancelled; this is disclosed to the user in the activation dialog before they are redirected.

Request Body

Response: 200 OK

{
  "authorization_url": "https://checkout.paystack.com/...",
  "access_code": "...",
  "reference": "inv_...",
  "amount_ngn": 15000,
  "plan_name": "Growth",
  "billing_type": "monthly"
}

Verifies a Paystack reference after the user returns from checkout and activates the subscription. Safe to call more than once for the same reference.

Request Body

Returns a compliance score plus NRS submission and VAT reporting statistics for the authenticated organisation. The score is a weighted average: NRS acceptance rate × 0.6 + VAT submission rate × 0.4.

Response: 200 OK

{
  "compliance_score": 87,
  "nrs_acceptance_rate": 92.5,
  "vat_submission_rate": 75.0,
  "invoice_stats": { "total": 120, "transmitted": 111, "failed": 2, "pending": 7 },
  "vat_stats": { "total": 8, "submitted": 6, "failed": 0, "pending": 2 },
  "vat_trend": [
    { "month": "Apr", "submitted": 1, "pending": 0 },
    { "month": "May", "submitted": 2, "pending": 1 }
  ],
  "nrs_submissions": [
    { "irn": "INV045-2741A890-20260701", "status": "acknowledged", "date": "2026-07-01", "amount": 85000.00 }
  ],
  "breakdown": [
    { "label": "Invoices transmitted", "value": 111, "total": 120 },
    { "label": "VAT reports submitted", "value": 6, "total": 8 }
  ]
}

Downloads the full NRS submission history (IRN, status, taxable/VAT/total amounts) as a CSV file.

Returns the authenticated organisation's own activity trail: every tracked create/update/delete action taken within it, sourced from the platform's immutable audit log. Scoped strictly to the caller's own organisation; there is no way to see another organisation's activity through this endpoint.

Query Parameters

Response: 200 OK

{
  "entries": [
    {
      "id": "225",
      "timestamp": "2026-09-09T13:09:31Z",
      "actor_name": "Adaeze Okonkwo",
      "action": "invoice.updated",
      "action_label": "Invoice Updated",
      "action_tone": "neutral",
      "target": "Invoice",
      "ip_address": "102.89.23.4",
      "status": "successful"
    }
  ],
  "meta": { "current_page": 1, "last_page": 6, "per_page": 10, "total": 59 }
}