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

Response: 201 Created

{
  "data": {
    "id": "uuid",
    "irn": "INV001-2741A890-20260701",
    "status": "draft",
    "total_amount": 150000.00,
    "vat_amount": 19565.22
  }
}

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.

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.

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.

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

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. Uses the same request body structure as POST /invoices. Immediately dispatches the validate and sign job. Returns 202 with the IRN as a reference for polling.

Response: 202 Accepted

{ "data": { "irn": "INV001-2741A890-20260701", "status": "draft" } }

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

Response: 200 OK

{
  "data": {
    "irn": "INV001-2741A890-20260701",
    "status": "signed",
    "qr_url": "https://storage.invota.ng/qr-codes/..."
  }
}

Submits up to 50 invoices in a single request. Returns a 207 Multi-Status response with a result for each invoice.

Request Body

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

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": "Commercial Invoice",  "resource_type": "invoice_types" },
    { "code": "381", "name": "Credit Note",         "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 }
}