Document Types

DocumentTypes

Resource for listing, creating and updating document types, and validating data against them. Access via client.documentTypes.

Methods

list(params?, options?)

Lists available document types with pagination.

const page = await client.documentTypes.list({ limit: 10 });

for (const docType of page.data) {
  console.log(docType.name, docType.codeType);
}

// Auto-pagination
for await (const docType of page.autoPagingIter()) {
  console.log(docType.name);
}

Resolve a codeType to the internal id that the other methods take:

// `search` also matches names and descriptions, so compare codeType
const matches = await client.documentTypes.list({ search: 'invoice' });
let id: string | undefined;
for await (const dt of matches.autoPagingIter()) {
  if (dt.codeType === 'invoice') {
    id = dt.id;
    break;
  }
}

Parameters: DocumentTypesListParams (optional) Returns: Promise<Page<DocumentType>>

get(id, options?)

Retrieves a single document type by its internal id. Unlike list(), it returns dslRules (null when the type has no rules).

const docType = await client.documentTypes.get('YOUR_DOCUMENT_TYPE_ID');
console.log(docType.name, docType.jsonSchema, docType.dslRules);

Parameters: id: string — the internal id, not the codeType Returns: Promise<DocumentType>

create(params, options?)

Creates a document type. dslRules is optional: omit it, or pass null or '', to create the type without business rules.

const docType = await client.documentTypes.create({
  name: 'Invoice',
  codeType: 'invoice',
  description: 'Supplier invoices',
  jsonSchema: { type: 'object', properties: { total: { type: 'number' } } },
  dslRules: 'field.total greaterThan 0',
});

Parameters: DocumentTypeCreateParams Returns: Promise<DocumentType> Throws: DSLValidationError when dslRules fails to compile. Nothing is saved.

update(id, params, options?)

Updates a document type. codeType cannot be changed after creation.

// Replace the rules
await client.documentTypes.update('YOUR_DOCUMENT_TYPE_ID', { dslRules: 'field.total greaterThan 0' });

// Clear them
await client.documentTypes.update('YOUR_DOCUMENT_TYPE_ID', { dslRules: null });

Omit dslRules to keep the stored rules. When it is omitted, the API re-checks the syntax of the stored rules: if they no longer compile, the update fails until new rules are sent.

Parameters: id: string (internal id), DocumentTypeUpdateParams Returns: Promise<DocumentType> Throws: DSLValidationError when dslRules fails to compile. Nothing is saved.

validate(id, data, params?, options?)

Validates a document's data against a document type, without running OCR or changing the type. It runs the type's JSON Schema and DSL rules.

The call succeeds even when the data has errors: check valid (or isValidationValid) and read the structured issues.

const result = await client.documentTypes.validate('YOUR_DOCUMENT_TYPE_ID', extracted);

if (!result.valid) {
  for (const issue of result.issues ?? []) {
    console.log(issue.field, issue.code, issue.message);
  }
}

Pass dslRules to test temporary rules instead of the stored ones, without saving them (dry-run). The JSON Schema still runs. null or '' tests without DSL rules.

const result = await client.documentTypes.validate('YOUR_DOCUMENT_TYPE_ID', extracted, {
  dslRules: 'field.total greaterThan 0',
});

Without dslRules, data is sent as the whole request body. A document that has both data and dslRules at its root is reserved by the API for dry-run requests, so validate such a document by passing dslRules.

Parameters: id: string (internal id), data: unknown, DocumentTypeValidateParams (optional) Returns: Promise<ValidationResult> Throws: DocuTrayError when data is undefined, before any request is sent. DSLValidationError when dslRules fails to compile.

Raw Responses

Access raw HTTP response details via withRawResponse:

const raw = await client.documentTypes.withRawResponse.list();
console.log(raw.statusCode);

withRawResponse.get(), create() and update() return the API body as is, with the document type inside a { data } envelope (DocumentTypeEnvelope); the regular methods unwrap it.