Compliance Alerts API¶

Applies to: All subscriptions

Purpose¶

Describe the two endpoints the Attention Center reads, for teams that want the same alerts in their own dashboard or ticketing system.

Which screen uses this: the earlier Attention Center. A registration with COMPLIANCE_INTELLIGENCE_V2 switched on uses the finding-based Attention API instead. This API stays until every registration has moved.

The one thing to rely on: the count on an alert and the documents returned for it come from the same query. If an alert says 17, its document list has 17 rows (up to 5,000). You never need to rebuild the list yourself by filtering another endpoint.

These are application endpoints, not a versioned integration contract (see Endpoint Index). The response shape may change between releases; pin to the fields listed below and ignore the rest.

Audience¶

Integration developers and administrators pulling Complifly's compliance alerts into another system.

Prerequisites¶

API Authentication — a user token whose role holds dashboard.view. Every role does.
An x-gstin header naming one of the caller's permitted GSTINs. Alerts are always for one registration; there is no cross-registration call.

Reference¶

Method	Path	Returns
`GET`	`/api/dashboard/compliance-alerts`	Open alerts for the GSTIN, most urgent first
`GET`	`/api/dashboard/compliance-alerts/{key}/documents`	The documents behind one alert

`GET /api/dashboard/compliance-alerts`¶

Query parameter fresh=1 skips the server's 60-second cache. Without it, results can be up to 60 seconds old.

Response: an array, sorted by severity, then value at risk, then count. An alert with nothing open is left out — an empty array means nothing needs action.

[
  {
    "key": "IRN_WINDOW",
    "severity": "CRITICAL",
    "count": 14,
    "criticalCount": 2,
    "title": "Invoices nearing the IRN deadline",
    "reason": "14 invoices dated 2 Sep–8 Sep have no IRN. NIC stops accepting an invoice 30 days after its date — the first closes on 2 Oct. 2 have 3 days or less left.",
    "impact": "After its deadline an invoice cannot be e-invoiced and has to be reissued under a new number and date. ₹7.1 L is at risk.",
    "action": { "label": "View invoices", "route": "/intelligence/reports?tab=irn&alert=IRN_WINDOW" },
    "valueAtRisk": 705756,
    "parties": 2
  }
]

Field	Meaning
`key`	Stable identifier. Use it, not `title`, to tell alerts apart
`severity`	`CRITICAL`, `HIGH`, `MEDIUM` or `LOW` (table below)
`count`	Documents affected. `null` for an alert that is a rate, not a number of documents
`criticalCount`	How many of `count` are in the most urgent band
`reason`, `impact`	Plain-language text, written for the user who has to act
`action.route`	Screen path in the Complifly app that opens the affected documents
`valueAtRisk`	Sum of invoice value (₹) across the documents, where it applies; otherwise `null`
`parties`	Number of distinct customers among the documents, where it applies
`category`	Same as `title`. Kept for older callers; do not build on it

Alert keys¶

`key`	Severity	Raised when	Cleared when
`IRN_WINDOW`	`CRITICAL` if any invoice has 3 days or less left, else `HIGH`	An invoice is 23–30 days old and has no IRN	The IRN is generated, or the invoice ages past 30 days
`IRN_WINDOW_PASSED`	`HIGH`	An invoice is more than 30 days old and has no IRN	An IRN exists for it, or the document is removed
`IRN_FAILED`	`HIGH`	NIC's latest answer for the invoice was a rejection	A later IRN request succeeds
`EWB_FAILED`	`HIGH`	The IRN exists but NIC rejected the e-way bill, and none is held	An e-way bill is generated
`EWB_EXPIRING_24H`	`CRITICAL` if any expires within 8 hours, else `MEDIUM`	An active e-way bill expires within 24 hours	It is extended, delivered or cancelled — or it expires
`EWB_EXPIRED`	`CRITICAL` if any expired in the last 8 hours, else `MEDIUM`	An e-way bill is past validity and not marked delivered or cancelled	It is marked delivered, or cancelled
`RULE_IRN_HIGH_CANCEL_RATE`	`MEDIUM`	More than 15% of the last 30 days' IRNs were cancelled (from Run Compliance Scan)	The next scan finds the rate back under 15%

Notes that change what you build:

The two IRN deadline keys were renamed on 2026-10-06. IRN_APPROACHING_WINDOW is now IRN_WINDOW and IRN_PAST_WINDOW is now IRN_WINDOW_PASSED — the same names the Attention API uses for the same checks. The response carries only the new keys. The /documents endpoint below still accepts the old ones and answers with the new key, so a saved link keeps working; anything that compares key against the old strings must be updated. (The old names were also used by two Help Centre statuses about the 24-hour IRN cancellation window, an unrelated rule; those are now IRN_CANCEL_WINDOW_CLOSED / IRN_CANCEL_WINDOW_CLOSING.)
"No IRN" excludes e-way-bill-only documents. Delivery challans, bills of supply and bills of entry loaded only to raise an e-way bill never get an IRN, so they never appear in the IRN deadline alerts.
The 30-day limit is applied to every registration. Per-registration applicability is planned; until it ships, a registration below NIC's turnover threshold still sees these alerts.
The 8-hour extension window is NIC's current rule. Confirm against the current NIC advisory before automating anything on it.

`GET /api/dashboard/compliance-alerts/{key}/documents`¶

{key} is one of IRN_WINDOW_PASSED, IRN_WINDOW, IRN_FAILED, EWB_FAILED, EWB_EXPIRED, EWB_EXPIRING_24H.

{ "key": "IRN_FAILED", "kind": "irn", "count": 87, "truncated": false, "items": [ { "inv_hdr_id": "695", "doc_no": "INMF23-000000326", "...": "..." } ] }

kind is irn (invoice rows: inv_hdr_id, doc_no, doc_date, buyer_gstin, total_invoice_value, irn_status, days_left, nic_error_code, nic_error_message, …) or ewb (e-way bill rows: ewb_no, doc_no, vehicle_no, status, ewb_valid_till, hours_left, …).
ewb_valid_till is returned as YYYY-MM-DD HH:mm:ss (IST), whatever format NIC originally sent.
At most 5,000 rows. truncated: true means there were more; count is then 5,000, not the total — read the total from the alert itself.

Errors¶

HTTP	Body	When
`401`	`{"code":"TOKEN_MISSING"}`	No token
`403`	permission / GSTIN error	The token's role lacks `dashboard.view`, or `x-gstin` is not one of the caller's GSTINs
`404`	`{"code":"UNKNOWN_ALERT_KEY"}`	`{key}` is not in the list above
`500`	`{"error":"…"}`	Database error — retry; if it persists, raise a support ticket with the time of the call

Validation¶

Call the alerts endpoint, then the documents endpoint for each key that has a count. The row count matches count (unless truncated).
Open the action.route in the app as the same user — the screen shows the same number in its banner.

Troubleshooting¶

Symptom	Cause	Action
An alert stays after the documents were fixed	The 60-second cache	Call again with `fresh=1`
An expected invoice is missing from the IRN deadline alerts	It already has an IRN record marked successful or cancelled, or it was loaded as an e-way-bill-only document	Check the document in the IRN workbench
`RULE_IRN_HIGH_CANCEL_RATE` never appears	It is only evaluated when someone runs Run Compliance Scan	Run the scan from the Attention Center