Document Types

Document Types resource for document type catalog operations.

AsyncDocumentTypes

Asynchronous document type operations.

Example:

>>> async with AsyncClient(api_key="...") as client:
    ...     page = await client.document_types.list()
    ...     for doc_type in page.data:
    ...         print(f"{doc_type.codeType}: {doc_type.name}")
    >>>
    >>> # Iterate through all document types across pages
    >>> async for doc_type in (await client.document_types.list()).auto_paging_iter_async():
    ...     print(doc_type.name)

Arguments:

client: The parent async client instance.

Methods:

create

def create(self, name: str, code_type: str, description: str, json_schema: dict[str, Any], is_draft: bool | None = None, prompt_hints: str | None = None, identify_prompt_hints: str | None = None, conversion_mode: ConversionMode | None = None, keep_property_ordering: bool | None = None, bounding_boxes_enabled: bool | None = None, conversion_spec: dict[str, Any] | None = None, dsl_rules: str | None = None, is_public: bool | None = None) -> DocumentType

Create a new document type.

Arguments:

name: Document type name (min 2 characters). code_type: Unique code identifier (lowercase alphanumeric and underscores). The API prefixes it with the organization slug when missing ("invoice" is stored as "acme_invoice"). description: Document type description (min 1 character). json_schema: JSON Schema for document validation. is_draft: Whether the document type is a draft. Defaults to True. prompt_hints: Hints for OCR prompt processing. identify_prompt_hints: Hints for document identification prompt. conversion_mode: Processing mode ("json", "toon", or "multi_prompt"). keep_property_ordering: Preserve property ordering in schema. bounding_boxes_enabled: Also return per-field locations (admin API keys only). conversion_spec: Spec mapping extracted JSON to CSV/Excel export columns. dsl_rules: DSL validation rules (64 KiB max). Invalid syntax raises DSLValidationError. is_public: Whether the document type is publicly available.

Returns:

The created document type.

get

def get(self, type_id: str) -> DocumentType

Get a specific document type by ID.

Arguments:

type_id: The document type's internal ID (not its codeType).

Returns:

The document type details including schema.

get_by_code

def get_by_code(self, code: str) -> DocumentType

Get a document type by its codeType.

Looks the code up with list(search=code) across all pages (100 per request) and fetches the match with get(), which includes the schema. Codes of your organization's own types carry its slug as a prefix, so pass the full code (e.g. "acme_invoice").

Arguments:

code: The exact codeType of the document type.

Returns:

The document type details including schema.

Raises:

NotFoundError: If no accessible document type has this exact code.

Example:

>>> doc_type = await client.document_types.get_by_code("acme_invoice")
    >>> print(doc_type.id)

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None) -> AsyncPage[DocumentType]

List available document types.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. Defaults to server default. search: Search term matched against name, codeType and description.

Returns:

An AsyncPage of document types with pagination support.

update

def update(self, type_id: str, name: str | None = None, description: str | None = None, json_schema: dict[str, Any] | None = None, is_draft: bool | None = None, prompt_hints: str | None = None, identify_prompt_hints: str | None = None, conversion_mode: ConversionMode | None = None, keep_property_ordering: bool | None = None, bounding_boxes_enabled: bool | None = None, conversion_spec: dict[str, Any] | None | NotGiven = NOT_GIVEN, dsl_rules: str | None | NotGiven = NOT_GIVEN, is_public: bool | None = None) -> DocumentType

Update an existing document type.

All fields are optional; only provided fields will be updated.

Arguments:

type_id: The document type's internal ID (not its codeType) to update. name: New document type name. description: New description. json_schema: New JSON Schema for document validation. is_draft: New draft status. prompt_hints: New OCR prompt hints. identify_prompt_hints: New identification prompt hints. conversion_mode: New processing mode. keep_property_ordering: New property ordering setting. bounding_boxes_enabled: Also return per-field locations (admin API keys only). conversion_spec: New export spec. None clears it; omit to keep it. dsl_rules: New DSL validation rules (64 KiB max). None or "" clears them; omit to keep the saved rules. Invalid syntax raises DSLValidationError. is_public: New public/private flag.

Returns:

The updated document type.

validate

def validate(self, type_id: str, data: dict[str, Any], dsl_rules: str | None | NotGiven = NOT_GIVEN) -> ValidationResult

Validate JSON data against a document type's schema.

Arguments:

type_id: The document type's internal ID (not its codeType) to validate against. data: The JSON data to validate. dsl_rules: Temporary DSL rules for a dry run. They replace the stored rules for this call only (JSON Schema still runs); None or "" validates without DSL. Omit to use the stored rules.

Returns:

Validation result with errors and warnings.

Properties:

• with_raw_response : Access methods that return raw HTTP responses.

DocumentTypes

Synchronous document type operations.

Example:

>>> client = Client(api_key="...")
    >>> page = client.document_types.list()
    >>> for doc_type in page.data:
    ...     print(f"{doc_type.codeType}: {doc_type.name}")
    >>>
    >>> # Iterate through all document types across pages
    >>> for doc_type in client.document_types.list().auto_paging_iter():
    ...     print(doc_type.name)

Arguments:

client: The parent client instance.

Methods:

create

def create(self, name: str, code_type: str, description: str, json_schema: dict[str, Any], is_draft: bool | None = None, prompt_hints: str | None = None, identify_prompt_hints: str | None = None, conversion_mode: ConversionMode | None = None, keep_property_ordering: bool | None = None, bounding_boxes_enabled: bool | None = None, conversion_spec: dict[str, Any] | None = None, dsl_rules: str | None = None, is_public: bool | None = None) -> DocumentType

Create a new document type.

Arguments:

name: Document type name (min 2 characters). code_type: Unique code identifier (lowercase alphanumeric and underscores). The API prefixes it with the organization slug when missing ("invoice" is stored as "acme_invoice"). description: Document type description (min 1 character). json_schema: JSON Schema for document validation. is_draft: Whether the document type is a draft. Defaults to True. prompt_hints: Hints for OCR prompt processing. identify_prompt_hints: Hints for document identification prompt. conversion_mode: Processing mode ("json", "toon", or "multi_prompt"). keep_property_ordering: Preserve property ordering in schema. bounding_boxes_enabled: Also return per-field locations (admin API keys only). conversion_spec: Spec mapping extracted JSON to CSV/Excel export columns. dsl_rules: DSL validation rules (64 KiB max). Invalid syntax raises DSLValidationError. is_public: Whether the document type is publicly available.

Returns:

The created document type.

Raises:

ConflictError: If a document type with that code_type already exists.

Example:

>>> doc_type = client.document_types.create(
    ...     name="Invoice",
    ...     code_type="invoice",
    ...     description="Invoice documents with line items",
    ...     json_schema={
    ...         "type": "object",
    ...         "properties": {
    ...             "invoice_number": {"type": "string"},
    ...             "total": {"type": "number"},
    ...         },
    ...     },
    ... )
    >>> print(f"Created: {doc_type.id}")

get

def get(self, type_id: str) -> DocumentType

Get a specific document type by ID.

Arguments:

type_id: The document type's internal ID (not its codeType).

Returns:

The document type details including schema.

Raises:

NotFoundError: If the document type doesn't exist.

Example:

>>> doc_type = client.document_types.get("cm0example0000000000000id")
    >>> print(f"Name: {doc_type.name}")
    >>> print(f"Schema: {doc_type.jsonSchema}")

get_by_code

def get_by_code(self, code: str) -> DocumentType

Get a document type by its codeType.

Looks the code up with list(search=code) across all pages (100 per request) and fetches the match with get(), which includes the schema. Codes of your organization's own types carry its slug as a prefix, so pass the full code (e.g. "acme_invoice").

Arguments:

code: The exact codeType of the document type.

Returns:

The document type details including schema.

Raises:

NotFoundError: If no accessible document type has this exact code.

Example:

>>> doc_type = client.document_types.get_by_code("acme_invoice")
    >>> print(doc_type.id)

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None) -> Page[DocumentType]

List available document types.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. Defaults to server default. search: Search term matched against name, codeType and description.

Returns:

A Page of document types with pagination support.

Example:

>>> # List all document types
    >>> page = client.document_types.list()
    >>> for doc_type in page.data:
    ...     print(doc_type.name)
    >>>
    >>> # Iterate through all pages
    >>> for page in client.document_types.list().iter_pages():
    ...     print(f"Page {page.page}: {len(page.data)} items")
    >>>
    >>> # Iterate through all items automatically
    >>> for doc_type in client.document_types.list().auto_paging_iter():
    ...     print(doc_type.name)
    >>>
    >>> # Search for specific types
    >>> page = client.document_types.list(search="invoice")

update

def update(self, type_id: str, name: str | None = None, description: str | None = None, json_schema: dict[str, Any] | None = None, is_draft: bool | None = None, prompt_hints: str | None = None, identify_prompt_hints: str | None = None, conversion_mode: ConversionMode | None = None, keep_property_ordering: bool | None = None, bounding_boxes_enabled: bool | None = None, conversion_spec: dict[str, Any] | None | NotGiven = NOT_GIVEN, dsl_rules: str | None | NotGiven = NOT_GIVEN, is_public: bool | None = None) -> DocumentType

Update an existing document type.

All fields are optional; only provided fields will be updated.

Arguments:

type_id: The document type's internal ID (not its codeType) to update. name: New document type name. description: New description. json_schema: New JSON Schema for document validation. is_draft: New draft status. prompt_hints: New OCR prompt hints. identify_prompt_hints: New identification prompt hints. conversion_mode: New processing mode. keep_property_ordering: New property ordering setting. bounding_boxes_enabled: Also return per-field locations (admin API keys only). conversion_spec: New export spec. None clears it; omit to keep it. dsl_rules: New DSL validation rules (64 KiB max). None or "" clears them; omit to keep the saved rules. Invalid syntax raises DSLValidationError. is_public: New public/private flag.

Returns:

The updated document type.

Raises:

NotFoundError: If the document type doesn't exist. PermissionDeniedError: If insufficient permissions.

Example:

>>> doc_type = client.document_types.update(
    ...     "cm0example0000000000000id",
    ...     name="Updated Invoice",
    ...     is_draft=False,
    ... )
    >>> print(f"Updated: {doc_type.name}")

validate

def validate(self, type_id: str, data: dict[str, Any], dsl_rules: str | None | NotGiven = NOT_GIVEN) -> ValidationResult

Validate JSON data against a document type's schema.

This validates extracted data to check if it conforms to the document type's expected structure and requirements.

Arguments:

type_id: The document type's internal ID (not its codeType) to validate against. data: The JSON data to validate. dsl_rules: Temporary DSL rules for a dry run. They replace the stored rules for this call only (JSON Schema still runs); None or "" validates without DSL. Omit to use the stored rules.

Returns:

Validation result with errors and warnings.

Example:

>>> result = client.document_types.validate(
    ...     "cm0example0000000000000id",
    ...     {"invoice_number": "INV-001", "total": 100}
    ... )
    >>> if result.is_valid():
    ...     print("Data is valid!")
    >>> else:
    ...     for error in result.errors.messages:
    ...         print(f"Error: {error}")

Properties:

• with_raw_response : Access methods that return raw HTTP responses.