Create and manage document type configurations — the extraction schema, validation rules, and classification hints

Document Types

Document types (internally called contexts) define how 9thSense processes a particular class of document. Each document type specifies an extraction schema, validation rules, classification hints, and the pipeline steps to run.

📝

The Library ships 40+ pre-built document types covering identity, financial, travel, and business documents. You can use them as-is, customise them, or create entirely new ones.

Document Type Object

context_idstring

Unique snake_case identifier (e.g. "pan_card", "aadhaar").

tenant_idstring

Tenant that owns this type. Empty string for global (shared) types.

display_namestring

Human-readable name (e.g. "PAN Card").

input_typestring

"document" or "image".

analysis_typestring

"extraction", "scene_understanding", or "classification".

model_hintstring

"vlm" for documents/images, "llm" for text-only processing.

categorystring

"identity", "financial", "travel", "business", "scene", or "other".

output_schemaobject

Field definitions: { field_name: type_hint_string }. E.g. { "name": "string", "date_of_birth": "YYYY-MM-DD or null" }.

validation_rulesobject

Per-field rules: { field_name: { required: bool, regex: "...", mask: bool, format: "..." } }.

classify_hintsstring[]

Keywords and phrases that uniquely identify this document type (used by the classifier).

pipeline_stepsstring[]

Ordered list of pipeline steps (e.g. ["classify", "extract", "validate"]).

prompt_hintstring

Extraction guidance injected into the VLM prompt — format quirks, common gotchas.

enabledboolean

Whether this type is active.

CRUD Endpoints

Create Document Type

POST /v1/document-types

Requires scope: write. Returns 201.

Request body:

context_idstringrequired

Unique snake_case ID (e.g. "vehicle_rc").

display_namestringrequired

Human-readable name.

tenant_idstring

Tenant to scope this type to. Leave empty for a global type.

output_schemaobjectrequired

Field definitions mapping field names to type hint strings.

validation_rulesobject

Per-field validation rules.

classify_hintsstring[]

Keywords for classification.

pipeline_stepsstring[]

Ordered pipeline steps.

prompt_hintstring

Extraction guidance for the VLM.

categorystring

One of: identity, financial, travel, business, scene, other.

input_typestring

"document" or "image". Default "document".

analysis_typestring

"extraction", "scene_understanding", or "classification". Default "extraction".

model_hintstring

"vlm" or "llm". Default "vlm".

enabledboolean

Whether to enable the type immediately. Default true.

Example request:

{
  "context_id": "vehicle_rc",
  "display_name": "Vehicle Registration Certificate",
  "tenant_id": "acme-corp",
  "category": "identity",
  "output_schema": {
    "registration_number": "string",
    "owner_name": "string",
    "vehicle_class": "string",
    "fuel_type": "string",
    "registration_date": "YYYY-MM-DD or null"
  },
  "validation_rules": {
    "registration_number": { "required": true, "mask": true },
    "owner_name": { "required": true }
  },
  "classify_hints": ["vehicle registration", "RC book", "Motor Vehicles Act"],
  "pipeline_steps": ["classify", "extract", "validate"]
}

Response (201): Document Type object.

List Document Types

GET /v1/document-types

Requires scope: read.

Query parameters:

tenant_idstring

Filter by tenant. Returns global types when empty.

Response (200): Array of Document Type objects.

Get Document Type

GET /v1/document-types/{context_id}

Requires scope: read. Falls back to the global (empty tenant) version if no tenant-specific type is found.

context_idstringrequired

Document type ID (e.g. "pan_card").

tenant_idstring

Tenant to scope the lookup.

Update Document Type

PUT /v1/document-types/{context_id}

Requires scope: write. Automatically snapshots the current state before applying the update.

context_idstringrequired
tenant_idstring

Request body: Same fields as Create (all optional on update).

Delete Document Type

DELETE /v1/document-types/{context_id}

Requires scope: write. Returns 204 No Content.

context_idstringrequired
tenant_idstring

Lock Fields (Progressive Schema Refinement)

PATCH /v1/document-types/{context_id}/lock-fields

Requires scope: write. Merges new fields into the existing output_schema and optionally auto-suggests validation rules for the added fields. Use this after a discover run to commit discovered fields to the schema.

context_idstringrequired
tenant_idstring

Request body:

fieldsobjectrequired

Map of { field_name: type_hint } to merge into the schema.

rulesobject

Explicit validation rules to set for specific fields.

auto_suggestboolean

If true, auto-generates validation rules for fields that don't have explicit rules (uses field name heuristics). Default false.

List Document Type Versions

GET /v1/document-types/{context_id}/versions

Requires scope: read. Returns the version history of a document type.

context_idstringrequired

Response (200):

idstring
UUID of the version snapshot.
context_idstring
tenant_idstring
display_namestring
configobject
Full configuration at the time of snapshot.
notestring
Auto-generated or manual note.
created_atstring

AI-Assisted Creation

Discover from Sample Documents

POST /v1/document-types/discover

Requires scope: write. Upload 1–3 sample documents — 9thSense uses a VLM to identify the document type, extract all fields, suggest an output schema, suggest validation rules, and generate classification hints.

Request body:

documentsobject[]required

Array of sample document objects. Each: { "data": "<base64>", "mime_type": "image/jpeg" }. Up to 3 samples — more samples improve field coverage.

Response (200):

context_idstring
Auto-generated slug (e.g. "pan_card").
display_namestring
Discovered document type name (e.g. "PAN Card").
suggested_schemaobject
Recommended output_schema.
suggested_rulesobject
Recommended validation_rules.
classify_hintsstring[]
Recommended classification keywords.
sample_extractionobject
Actual extracted values from the sample document.

Generate from Description

POST /v1/document-types/generate

Requires scope: write. Describe a document type in plain text — an LLM generates a complete configuration including schema, validation rules, classification hints, and extraction guidance.

Request body:

descriptionstringrequired

Plain-text description of the document type (e.g. "Indian driving license issued by transport department, has front and back sides, contains license number, name, DOB, address, vehicle classes").

tenant_idstring

Response (200):

context_idstring
display_namestring
categorystring
input_typestring
analysis_typestring
model_hintstring
suggested_schemaobject
suggested_rulesobject
classify_hintsstring[]
prompt_hintstring
PreviousCasesNextPipelines & Executions