Skip to content

title: Documents API description: The two read-only endpoints behind the Documents Workspace: one paged list of a registration's invoices and e-way bill documents together, and one document's detail. keywords: [documents, workspace, document detail, invoices, e-way bill documents, kind filter, api] modules: [einvoice, ewaybill] owner: engineering reviewed: 2026-10-10 cadence: per-release audience: [integrator] not_for: End users looking up a document. Use the Documents screen and its in-product help instead of this API reference. classification: CUSTOMER

Documents API

Applies to: e-Invoice and e-Way Bill, on registrations where DOCUMENTS_WORKSPACE, DOCUMENT_STATUS_V2 and ENTERPRISE_GRID_V2 are all switched on

Purpose

Describe the two endpoints the Documents Workspace reads, for teams that want one view of both kinds of document outside Complifly.

The one thing to rely on: a document has exactly one document_kind. It is EWB_DOC for documents loaded through the no-IRN route and for IGM challans and bills, and INVOICE for everything else. The list is the IRN Workbench's own paged list (same filters, sorting, paging, status vocabulary and row-level security) over both kinds, so a row is never repeated. An IGM challan that the two workbenches both show appears here once, as EWB_DOC.

What it is not: a way to act. There is no POST, PUT, PATCH or DELETE, and nothing here calls NIC. Generating, cancelling and updating a document stay in the IRN and e-way bill workbench endpoints; see the Endpoint index.

Audience

Integration developers who want a single document lookup, and administrators supporting users who ask why a document is missing from the screen.

Prerequisites

  • A signed-in user holding irn.view (to see invoices), ewb.view (to see e-way bill documents), or both, and the X-GSTIN header naming one registration (all is not accepted).
  • DOCUMENTS_WORKSPACE switched on for that registration, and DOCUMENT_STATUS_V2 and ENTERPRISE_GRID_V2. Only a Complifly Super Admin can switch these on.

Reference

Endpoints

Call Returns
GET /api/documents The paged-list contract (grid, page, size, total, pages, rows, optional facets) plus kinds, the kinds the caller may see. Each row carries document_kind
GET /api/documents/:id { document, irn, ewb, findings } for one document (:id is the document's inv_hdr_id, digits only)

The list

Query parameters are those of the paged IRN list, plus the kind filter: f=kind:in:INVOICE, f=kind:in:EWB_DOC, or none for both. kind is also a sort key and a facet (facets=only returns the counts per kind). A caller who may see only one kind gets only that kind whatever they send.

The detail

Part Holds
document The row as the list returns it, plus the canonical irn_state and ewb_state, irn, ack_no, ack_dt and taxable_value
irn irn, ackNo, ackDate, status, state, and attempts: the last five submissions (attemptNo, at, ms, outcome, errorCode, errorMessage, gsp)
ewb state, bills (number, status, dates, vehicle, transporter, origin, last error), partBUpdates and validityExtensions (counts)
findings Open Attention findings: id, rule, severity, status, dueAt, detectedAt, assigned (whether someone holds it, never who)

Raw NIC request and response payloads are never returned: an error is its code and message.

Errors

Code HTTP Meaning
FEATURE_DISABLED_BY_OPERATOR 403 DOCUMENTS_WORKSPACE is off for the registration, or a prerequisite is off (the body's missing lists which)
(no code; message begins "Forbidden") 403 The caller holds neither irn.view nor ewb.view
GSTIN_REQUIRED 400 X-GSTIN names no single registration
DOCUMENT_NOT_FOUND 404 No such document in this registration, or it is a kind the caller may not see. The two are not distinguishable by design
(grid contract codes) 400 The list query is malformed, for example an unknown filter key

See Platform error codes.

Validation

Call GET /api/documents?grid=2&facets=only and GET /api/documents?grid=2&size=10&f=kind:in:INVOICE: the second's total equals the INVOICE count in the first, for the same fy and month. Take any inv_hdr_id from a row and call GET /api/documents/{id}.

Troubleshooting

Symptom Cause Action
403 FEATURE_DISABLED_BY_OPERATOR with missing: ["ENTERPRISE_GRID_V2"] A prerequisite is off A Complifly Super Admin switches it on for that GSTIN
A document the IRN Workbench shows is not in the INVOICE list It is an IGM challan or bill, listed once as EWB_DOC Filter by EWB_DOC
The detail answers 404 for a document the list returned The caller's role lost the right to that kind between calls, or the X-GSTIN differs Repeat with the same X-GSTIN
The list is shorter than expected The screen's financial-year default is applied Remove fy and month