Subjects

A Subject models something your business tracks that is made of several documents — a purchase, a patient, a shipment, a claim. Each instance is a Case, and Tavnit files every incoming document into the right Case and extracts it with the right flow.

A flow handles one kind of document. A Subject sits one level up: it says “a purchase is a quote, a purchase order and an invoice”, gives every purchase a reference such as PT-0042, and keeps all of that purchase's documents, runs and checks together on one page.

• Several different documents belong to the same real-world thing, and you want them side by side
• Documents arrive by email over days or weeks, and each one must land on the right file
• You want to run comparisons or checklists across the documents of one Case — quotes against each other, an invoice against its order
• A partner or an agent sends documents that carry your reference number

1. 1Open Subjects and click “New Subject”.
2. 2Answer “What makes up each case?”: From your flows (pick the documents that make up a Case — one document type per flow), From an existing subject (duplicates its document types and checks) or Start from scratch.
3. 3Give it a Name and a Reference prefix of 1–8 letters or digits, such as PT. Tavnit warns you if another Subject already uses the prefix.
4. 4Optionally set the Case label (singular and plural) — for example “Purchase” and “Purchases”. The Subject's pages then say “New purchase” instead of the generic term.
5. 5Click Create, then review the Document types tab.

Each document type is a slot in every Case, processed by one flow. When a document is filed into a slot, Tavnit starts a run of that flow, and the run's results appear on the Case.

Add a type from the Document types tab with a Name (e.g. “Quote”) and a Flow. Two switches control each type:

A Case is opened by hand, over the API, or by an agent. Its reference is issued automatically from the prefix and a counter — gap-free and never reused.

1. 1On the Subject, click New <case label> (for example “New purchase”).
2. 2Type a name. It must be unique within the Subject, because a document whose email subject or filename equals the name is filed into this Case.
3. 3Click Create. The Case gets the next reference, such as PT-0043.

The Case page brings everything together:

• The reference, name, workflow status and Open or Closed state
• Its documents grouped by document type, each with its routing status and a View results link to the run
• A drop zone to upload documents straight into the Case (you choose the document type when the Subject has more than one)
• Email this <case label> — the Case's own address, when email intake is on
• The Checks section, with the matches and inspections already run on the Case

Filing a document into a Case never uses AI. Tavnit looks for the Case reference, then for an exact Case name. If neither gives a single clear answer, the document is held for a person rather than guessed.

This applies to documents sent to the intake email, uploaded with Add docs on the Subject, or posted to the Subject over the API.

References are read tolerantly: PT-0042, pt 42 and PT0042 all mean Case 42. Tavnit checks the places a reference can appear in order of authority, and the first one that contains a reference decides:

• One reference that matches a Case: the document is filed there.
• Two different references in the same place: held as ambiguous.
• A reference that matches no Case: held — a mistyped number never falls back to a name match.
• No reference anywhere: Tavnit compares the email subject and the filename (without extension) with Case names — whole value, ignoring case and surrounding spaces. Never a partial match, never the body.

Once the Case is known, Tavnit picks the document type. A Subject with one document type needs no decision. With several types, an AI classifier reads the first page and chooses among them — this is the only AI step.

1. 1Open the Subject's Email intake tab and turn the switch on.
2. 2Copy the Intake address and forward documents to it, or give it to suppliers and partners.
3. 3Optionally restrict which senders are accepted with the sender whitelist on the same tab.

Three things route an emailed attachment to its Case:

• A reference such as PT-0042 in the subject, body or filename. Replies keep the subject line, so a whole thread follows the Case automatically.
• The Case's own address: the intake address with the reference added as a plus-tag, e.g. intake+PT-0042@…. It is shown on the Case page as Email this <case label>.
• An email subject or filename that exactly equals a Case name.

Each attachment is handled separately. For the address formats and the attachment types Tavnit accepts, see email integration.

Anything Tavnit cannot file with certainty lands in Held documents, with the reason written under it. Nothing is processed until someone decides.

For each held document you can:

• Assign it: pick a Case and a document type. Tavnit starts the flow run on the stored file — no new upload. Assigning to a closed Case is allowed, because a person chose it explicitly.
• New <case label> from doc: open a new Case and file the document into it in one step.
• Discard it.

A file Tavnit cannot process at all — an unsupported type or an invalid file — shows as Failed instead of Held. Document statuses are Queued, Routing, Routed, Held, Failed and Discarded.

Click Close on a Case when its file is complete. From then on, documents routed to it automatically are held instead of filed, so a late reply cannot reopen finished work by accident. The Case page says it is closed, and uploads on the Case page are hidden.

Reopen restores automatic intake. Closing is always reversible.

Bind Matchers and Inspectors to the Subject once, then run them on any Case from its page. They work on the Case's completed runs — nothing is uploaded or extracted again.

Click Run next to a check. Its result is listed on the Case with its status and, for inspections, the verdict; open it for the full comparison or checklist.

An agent can file what it collects straight into a Subject. In the agent's delivery settings, choose the Subject, the field that gives the Case name, which captured files to file as which document type, optional fields to Store as case params, and what to do If the case already exists: Skip or Add missing documents.

Cases are matched by name, so running the agent again never creates a duplicate. Documents filed this way show an Agent link back to the agent run.

The Subject endpoints use the same X-API-Key header as the rest of the REST API:

• Admins and Owners create Subjects and bind Matchers and Inspectors. The creator of a Subject can also edit or delete it.
• Every member except HITL Only users works Cases: opens them, uploads, triages held documents, changes status, closes, reopens and runs checks.

A Subject can be deactivated instead of deleted: it stops accepting new documents and Cases, and Reactivate brings it back. See user roles.