Document Types

List, create, update, inspect, and validate Docutray document types and their JSON schemas — the fields each type extracts, with SDK and REST examples.

Document types define what data DocuTray extracts from your documents. Each type has a JSON schema that describes the fields to extract. Use the Document Types API to list available types, create custom types, update existing ones, inspect their schemas, and validate extracted data.

List Document Types

Retrieve all document types accessible to your organization, including public types and your custom types.

from docutray import Client

client = Client(api_key="YOUR_API_KEY")

# List all document types
page = client.document_types.list()

for doc_type in page.data:
    print(f"{doc_type.codeType}: {doc_type.name}")

# Auto-paginate through all results
for doc_type in client.document_types.list().auto_paging_iter():
    print(f"{doc_type.codeType}: {doc_type.name}")

Response

# page is a Page[DocumentType]
print(f"Total: {page.pagination.total}")
print(f"Page: {page.pagination.page}")

for dt in page.data:
    print(f"  {dt.name} ({dt.codeType})")
    print(f"  Public: {dt.isPublic}, Draft: {dt.isDraft}")

Search and Pagination

# Search by name or code
page = client.document_types.list(search="invoice")

# Manual pagination
page = client.document_types.list(page=1, limit=10)

# Iterate through all pages
for page_chunk in client.document_types.list().iter_pages():
    print(f"Page {page_chunk.page}: {len(page_chunk.data)} items")

Get Document Type

Retrieve a specific document type by ID, including its full JSON schema.

doc_type = client.document_types.get("dt_abc123")

print(f"Name: {doc_type.name}")
print(f"Code: {doc_type.codeType}")
print(f"Description: {doc_type.description}")
print(f"Schema: {doc_type.schema_}")

Create Document Type

Create a new document type with a JSON schema that defines the fields to extract.

from docutray import Client

client = Client(api_key="YOUR_API_KEY")

doc_type = client.document_types.create(
    name="Purchase Order",
    code_type="myorg_purchase_order",
    description="Standard purchase order document",
    json_schema={
        "type": "object",
        "properties": {
            "po_number": {"type": "string", "description": "Purchase order number"},
            "vendor": {"type": "string", "description": "Vendor name"},
            "total": {"type": "number", "description": "Total amount"},
        },
    },
    is_draft=True,
    conversion_mode="json",
)

print(f"Created: {doc_type.name} ({doc_type.codeType})")
print(f"Status: {doc_type.status}")

Response

{
  "data": {
    "id": "cm5vm9hx30001m5cgh0p9v8qa",
    "codeType": "myorg_purchase_order",
    "name": "Purchase Order",
    "description": "Standard purchase order document",
    "isPublic": false,
    "isDraft": true,
    "status": "draft",
    "createdAt": "2024-03-15T10:30:00.000Z",
    "updatedAt": "2024-03-15T10:30:00.000Z"
  }
}

Admin vs Non-Admin Behavior

Behavior	Non-Admin Users	Admin Users
`codeType` prefix	Must start with org slug (e.g., `myorg_`)	No prefix required
`codeType` min length	At least 3 characters after prefix	No minimum after prefix
`isPublic`	Forced to `false`	Can set to `true`
`source`	Set to `USER`	Defaults to `ADMIN`

Error Handling

from docutray import Client, ConflictError, BadRequestError, PermissionDeniedError

client = Client(api_key="YOUR_API_KEY")

try:
    doc_type = client.document_types.create(
        name="Purchase Order",
        code_type="myorg_purchase_order",
        description="Standard purchase order document",
        json_schema={"type": "object", "properties": {}},
    )
except ConflictError:
    # 409: codeType already exists
    print("A document type with this codeType already exists")
except BadRequestError as e:
    # 400: Invalid request body
    print(f"Validation error: {e.message}")
except PermissionDeniedError:
    # 403: Insufficient permissions
    print("You don't have permission to create this document type")

Update Document Type

Update an existing document type. All fields are optional. The codeType field is immutable and will be ignored if provided.

from docutray import Client

client = Client(api_key="YOUR_API_KEY")

doc_type = client.document_types.update(
    "cm5vm9hx30001m5cgh0p9v8qa",
    name="Updated Purchase Order",
    description="Updated description",
    is_draft=False,  # Publish the document type
    prompt_hints="Focus on extracting line items and totals",
)

print(f"Updated: {doc_type.name}")
print(f"Status: {doc_type.status}")  # "published" when isDraft=False

Response

{
  "data": {
    "id": "cm5vm9hx30001m5cgh0p9v8qa",
    "codeType": "myorg_purchase_order",
    "name": "Updated Purchase Order",
    "description": "Updated description",
    "isPublic": false,
    "isDraft": false,
    "status": "published",
    "createdAt": "2024-03-15T10:30:00.000Z",
    "updatedAt": "2024-03-16T14:20:00.000Z"
  }
}

Permissions

Non-admin users can only update document types they created.
Non-admin users cannot set isPublic to true.
When isDraft changes, the status field is automatically updated.
A version snapshot is created before each update.

Error Handling

from docutray import Client, NotFoundError, PermissionDeniedError, BadRequestError

client = Client(api_key="YOUR_API_KEY")

try:
    doc_type = client.document_types.update(
        "cm5vm9hx30001m5cgh0p9v8qa",
        name="Updated Name",
    )
except NotFoundError:
    # 404: Document type not found
    print("Document type not found")
except PermissionDeniedError:
    # 403: Can only update your own document types
    print("You don't have permission to update this document type")
except BadRequestError as e:
    # 400: Invalid request body
    print(f"Validation error: {e.message}")

Validate Data

Validate extracted data against a document type's schema. Useful for checking data quality after conversion or before submitting to downstream systems.

result = client.document_types.validate(
    "dt_invoice",
    {"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}")
    for warning in result.warnings.messages:
        print(f"Warning: {warning}")

Understanding Schemas

Each document type has a JSON schema that defines the fields DocuTray extracts. For example, an invoice schema might look like:

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Invoice number or identifier"
    },
    "issue_date": {
      "type": "string",
      "format": "date",
      "description": "Date the invoice was issued"
    },
    "vendor_name": {
      "type": "string",
      "description": "Name of the issuing company"
    },
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "number" },
          "unit_price": { "type": "number" },
          "amount": { "type": "number" }
        }
      }
    },
    "subtotal": { "type": "number" },
    "tax": { "type": "number" },
    "total": { "type": "number" }
  }
}

The schema determines which fields are extracted during conversion and what data types they should have.

Parameters

List Parameters

Parameter	Type	Required	Description
`search`	string	No	Search by name, code, or description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page, 1-100 (default: 20)

Get Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Document type ID

Create Parameters (Request Body)

Parameter	Type	Required	Description
`name`	string	Yes	Document type name (min 2 characters)
`codeType`	string	Yes	Unique code identifier (`^[a-z0-9_]+$`). Non-admin users must prefix with org slug.
`description`	string	Yes	Document type description
`jsonSchema`	object	Yes	JSON Schema for document validation
`isDraft`	boolean	No	Whether the document type is a draft (default: `true`)
`promptHints`	string	No	Hints for the OCR prompt
`identifyPromptHints`	string	No	Hints for the document identification prompt
`conversionMode`	string	No	Conversion mode: `json`, `toon`, or `multi_prompt` (default: `json`)
`keepPropertyOrdering`	boolean	No	Preserve property ordering in schema (default: `false`)
`isPublic`	boolean	No	Whether the document type is public (admin only)

Update Parameters

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Document type ID

Request Body

All fields are optional. The codeType field is immutable and cannot be changed.

Parameter	Type	Required	Description
`name`	string	No	Document type name
`description`	string	No	Document type description
`jsonSchema`	object	No	JSON Schema for document validation
`isDraft`	boolean	No	Whether the document type is a draft
`promptHints`	string	No	Hints for the OCR prompt
`identifyPromptHints`	string	No	Hints for the document identification prompt
`conversionMode`	string	No	Conversion mode: `json`, `toon`, or `multi_prompt`
`keepPropertyOrdering`	boolean	No	Preserve property ordering in schema
`isPublic`	boolean	No	Whether the document type is public (admin only)

Complete Code

from docutray import Client, NotFoundError, ConflictError, DocuTrayError

client = Client(api_key="YOUR_API_KEY")

try:
    # List available document types
    print("Available document types:")
    for doc_type in client.document_types.list().auto_paging_iter():
        status = "published" if not doc_type.isDraft else "draft"
        scope = "public" if doc_type.isPublic else "private"
        print(f"  [{status}/{scope}] {doc_type.name} ({doc_type.codeType})")

    # Get details for a specific type
    invoice_type = client.document_types.get("dt_abc123")
    print(f"\nSchema for {invoice_type.name}:")
    print(invoice_type.schema_)

    # Create a new document type
    new_type = client.document_types.create(
        name="Purchase Order",
        code_type="myorg_purchase_order",
        description="Standard purchase order document",
        json_schema={
            "type": "object",
            "properties": {
                "po_number": {"type": "string"},
                "total": {"type": "number"},
            },
        },
    )
    print(f"\nCreated: {new_type.name} ({new_type.codeType})")

    # Update the document type
    updated = client.document_types.update(
        new_type.id,
        name="Updated Purchase Order",
        is_draft=False,
    )
    print(f"Updated: {updated.name}, Status: {updated.status}")

except ConflictError:
    print("Document type with this codeType already exists")
except NotFoundError:
    print("Document type not found")
except DocuTrayError as e:
    print(f"Error: {e.message}")
finally:
    client.close()

SDK Reference

For detailed class and method documentation:

Document Types

On this page