Skip to content

title: Personal Views API description: The endpoints behind saved views on the IRN Workbench: list, save, rename or replace, make default, copy and delete a user's own views, and the view document they hold. keywords: [personal views, saved views, default view, workbench, filters, sort, density, api] modules: [einvoice] owner: engineering reviewed: 2026-10-12 cadence: per-release audience: [integrator] not_for: End users saving a view. Use the Views button on the IRN Workbench and its in-product help instead of this API reference. classification: CUSTOMER

Personal Views API

Applies to: e-Invoice, on registrations where PERSONAL_VIEWS and ENTERPRISE_GRID_V2 are switched on

Purpose

Describe the /api/views endpoints the IRN Workbench uses to save a user's own combinations of filters, financial year, sort and density, for teams that build their own front end on the paged list (see List Columns and Saved Layouts API).

The one thing to rely on: a view is private to the user who saved it, and is stored per user and per organisation. There is no way to read, list or change another user's view through this API, and nobody, an administrator included, has a route to do so. A view id that is not yours answers 404 VIEW_NOT_FOUND, exactly as one that does not exist.

Audience

Integration developers building their own front end on the paged IRN Workbench list, and administrators supporting users who ask why the Views button is missing.

Prerequisites

  • A signed-in user. The user and organisation come only from the verified token; any userId or orgId sent in a body, query string or header is ignored.
  • The X-GSTIN header: the control is read for that registration. With PERSONAL_VIEWS off, every call below answers 403 FEATURE_DISABLED_BY_OPERATOR and nothing is read or written. Only a Complifly Super Admin can switch it on.
  • No permission is needed beyond sign-in. A view only names columns, sorts and filters; which documents it shows is decided by the list endpoint, exactly as for any other request.

Reference

Endpoints

Call Purpose Success
GET /api/views?screen=einvoice_irn-workbench-table The caller's views for one screen, the default first, then by name 200 { views: [...] }
POST /api/views Save a view. Body: { screenKey, name, view, makeDefault? } 201 { view }
PUT /api/views/:id Rename and/or replace the content. Body: { name?, view? } 200 { view }
PUT /api/views/:id/default Make it the screen's default. Body { isDefault: false } clears it instead 200 { view }
POST /api/views/:id/clone Copy it as "Name (copy)", then "Name (copy 2)". Body: { name? }. A copy is never the default 201 { view }
DELETE /api/views/:id Delete it. Deleting one that is already gone is not an error 204

Only one screen can hold views today: einvoice_irn-workbench-table. Any other screenKey answers 400 VIEW_UNKNOWN_SCREEN.

A view

{ "v": 1,
  "sort":    [{ "key": "doc_date", "dir": "desc" }],
  "filters": [{ "key": "irn_state", "op": "in", "values": ["FAILED"] }],
  "period":  { "rel": "this_month" },
  "density": "comfortable" }
Field Rules
sort Up to 3 keys, each one the paged list can sort by (doc_no, doc_date, doc_type, buyer_name, supply_type, irn_status, total_invoice_value, taxable_value, created_at). ewb_status cannot be sorted
filters Only filters the IRN Workbench can show: supply_type, doc_type, irn_status or irn_state, ewb_status or ewb_state, each with one value. No date range, no multi-select, no search text
period The financial-year control: { "fy": "2026-27", "month": "04" } (month all or 01 to 12), or { "rel": "fy_current" \| "fy_previous" \| "this_month" \| "last_month" }
density compact or comfortable
columns Accepted (column keys, up to 150) but not used by the IRN Workbench, whose columns stay with Layout Management
anything else Refused. A view of more than 4,000 characters is refused

What the server checks. Beyond the shape, the view is turned into the exact request the paged list would send and given to the list's own parser; if the list would refuse it, so is the view. A view can therefore never hold something the list cannot request.

Relative periods do not freeze. A rel period is stored as the word and resolved against today (India Standard Time) each time the views are read, so "this month" opens on the current month next month. Every view in a response carries both forms:

Field Meaning
view What is stored
resolved The same, with rel replaced by the fy and month it means today, ready to apply
adjusted, dropped true and the names of any parts that no longer fit the screen (a retired sort key or status). They are left out of view and resolved; the stored row is untouched
isDefault At most one true per user and screen

Limits

20 views per user per screen; a name is 1 to 60 characters and unique per user and screen ignoring capitals.

Errors

Code HTTP Meaning
VIEW_INVALID 400 The view or name is not acceptable; message says which part
VIEW_UNKNOWN_SCREEN 400 The screen cannot hold views
VIEW_LIMIT 400 The user already has 20 views for the screen
VIEW_NOT_FOUND 404 No such view for this user (including one belonging to someone else)
VIEW_NAME_TAKEN 409 The user already has a view with that name for the screen
FEATURE_DISABLED_BY_OPERATOR 403 PERSONAL_VIEWS is off for the registration

See Platform error codes.

Validation

Save a view, list it, then request the paged list with the same sort and filters (resolved.sort, resolved.filters, resolved.fy, resolved.month): the totals are identical to the screen with the view applied.

Troubleshooting

Symptom Cause Action
Every call answers 403 FEATURE_DISABLED_BY_OPERATOR PERSONAL_VIEWS is off for the registration in X-GSTIN A Complifly Super Admin switches it on for that GSTIN
The calls work but the screen shows no Views button ENTERPRISE_GRID_V2 is off for the registration, or the user signed in before PERSONAL_VIEWS was switched on Switch on the paged list; the user signs in again (controls are read at sign-in)
404 VIEW_NOT_FOUND for a view the caller believes exists It belongs to another user or organisation, or was deleted Views are private; list the caller's own with GET /api/views
A saved view opens with part of it missing A sort key or status it used has since been retired; the response has adjusted: true and names the parts in dropped Save it again from the screen as it now stands
A "this month" view opens on the wrong month It was saved with an exact month, not Always open on the current month Update the view with that option ticked, or send period: { "rel": "this_month" }
400 VIEW_INVALID on a filter the list itself accepts A view may hold only what the screen can show: one value per dropdown, no date range, no search Use the list endpoint directly for those