Skip to content

title: Work Queues API description: The two read-only endpoints behind the Work Queue strip: the queue definitions and how many documents are in each queue for a registration. keywords: [work queues, ready for irn, in doubt, queue counts, stage lists, api] modules: [einvoice] owner: engineering reviewed: 2026-10-13 cadence: per-release audience: [integrator] not_for: End users working a queue. Use the Work queues row on the Launchpad and the IRN Workbench, and its in-product help, instead of this API reference. classification: CUSTOMER

Work Queues API

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

Purpose

Describe the two endpoints the Work Queue strip reads, for teams that want the same stage counts in their own dashboard.

The one thing to rely on: a queue's count is the total the paged IRN list returns when you ask it for that queue's filters (GET /api/irn/workbench?grid=2&f=… with the queue's filters), computed by the same engine under the same row-level security. A count and the list behind it cannot disagree, and you never need to rebuild a queue by filtering another endpoint.

What a queue is not: a case. A queue lists documents waiting at a workflow stage. There is no assignee, due date or escalation, no way to create, edit or close a queue through this API, and a document leaves a queue when its state changes. Problems that need tracking (a NIC rejection, an expiring e-way bill) are Attention Center findings; see the Attention API.

Audience

Integration developers who want stage counts outside Complifly, and administrators supporting users who ask why a queue shows a number.

Prerequisites

  • A signed-in user holding irn.view, and the X-GSTIN header naming one registration (all is not accepted: counts are per registration).
  • WORK_QUEUES switched on for that registration, and DOCUMENT_STATUS_V2 and ENTERPRISE_GRID_V2. Queues speak the canonical status states and open on the paged list. Only a Complifly Super Admin can switch these on.

Reference

Endpoints

Call Returns
GET /api/queues { queues: [{ id, title, description, screen, route, helpKey, filters }], attention: [{ rule, title, route }] }
GET /api/queues/counts { counts: { READY_FOR_IRN: 12, IN_DOUBT: 1 }, asOf, cachedForSeconds: 60 }

There is no POST, PUT, PATCH or DELETE.

The queues

Id Holds filters (the paged list's own form)
READY_FOR_IRN Documents with no IRN yet, and documents whose last attempt failed irn_state in NOT_GENERATED, FAILED
IN_DOUBT Documents NIC has not confirmed either way irn_state in IN_DOUBT

The two sets do not overlap, so a document is in at most one queue. Documents that already have an IRN, and cancelled ones, are in neither. To open a queue in your own list, send its filters as repeated f=irn_state:in:NOT_GENERATED,FAILED parameters.

Freshness and financial years

  • Counts may be up to 60 seconds old (cachedForSeconds); asOf says when they were taken. The list you open is always live.
  • A queue counts every financial year. A document waiting for an IRN is waiting whatever year it belongs to. The IRN Workbench therefore shows every financial year when a queue is open, so the list matches the count. If you add fy and month yourself the list will be narrower than the count.

Errors

Code HTTP Meaning
FEATURE_DISABLED_BY_OPERATOR 403 WORK_QUEUES is off for the registration, or a prerequisite is off (the body's missing lists which)
(no code; message begins "Forbidden: Your role") 403 The caller does not hold irn.view
(no code; error says X-GSTIN is required) 400 The X-GSTIN header is missing
GSTIN_REQUIRED 400 X-GSTIN names no single registration (a Super Admin sending all)

See Platform error codes.

Validation

Call GET /api/queues/counts, then GET /api/irn/workbench?grid=2&size=10&f=irn_state:in:NOT_GENERATED,FAILED (no fy): total equals the READY_FOR_IRN count, apart from documents that changed state in the last minute.

Troubleshooting

Symptom Cause Action
403 FEATURE_DISABLED_BY_OPERATOR with missing: ["DOCUMENT_STATUS_V2"] A prerequisite is off A Complifly Super Admin switches it on for that GSTIN
The queue row does not appear on the screen though the API answers The user signed in before the controls were switched on (a user's controls are read at sign-in), or ENTERPRISE_GRID_V2 is off for them Sign in again
The count is higher than the list I built myself My list had the current financial year applied Remove fy and month
A document is missing from the count It is EWB_ONLY, already has an IRN, or is cancelled, or it changed state in the last minute Open the document; counts refresh every minute
A chip shows a dash instead of a number The counts could not be loaded; the list still opens Reload; if it persists, check the registration's controls