> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beltic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Templates

> Learn how to create, manage, and use document templates for consistent document processing

## Overview

Document templates allow you to define reusable configurations for document processing. Templates include extraction schemas, fraud detection settings, and other processing parameters that can be applied to multiple documents.

Templates are particularly useful when you process similar documents repeatedly, as they eliminate the need to specify configuration for each document individually.

## Benefits of Using Templates

* **Consistency**: Ensure all documents of the same type are processed with identical settings
* **Efficiency**: Avoid repeating configuration in every document creation request
* **Maintainability**: Update template settings once to affect all future documents using that template
* **Organization**: Group related processing configurations together

## Creating a Template

### Validation Field Pattern

If you need date-based validation (for example "is this date recent enough?" or "is this date still valid?"), model it as:

* A date source field using `"custom:type": "date"`
* A separate boolean validation field with `beltic:validation`
* A `field_ref` pointing to the sibling source date field

This allows backend validation to compute the boolean result after extraction.

```json theme={null}
{
  "type": "object",
  "properties": {
    "issue_date": {
      "type": ["string", "null"],
      "custom:type": "date"
    },
    "is_recent": {
      "type": ["boolean", "null"],
      "beltic:validation": {
        "kind": "date_recency",
        "field_ref": "issue_date",
        "max_age_days": 90
      }
    }
  },
  "required": ["issue_date", "is_recent"]
}
```

<Steps>
  <Step title="Define the extraction schema">
    Create a JSON Schema that defines the structure of data you want to extract from documents. The schema must follow our [Schema rules](/guides/schema-requirements).

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": ["string", "null"],
          "description": "Invoice identifier"
        },
        "amount": {
          "type": ["number", "null"],
          "description": "Total invoice amount"
        },
        "date": {
          "type": ["string", "null"],
          "description": "Invoice date"
        },
        "vendor": {
          "type": ["string", "null"],
          "description": "Vendor name"
        }
      },
      "required": ["invoice_number", "amount", "date", "vendor"]
    }
    ```
  </Step>

  <Step title="Configure extraction and fraud detection">
    Set up your extraction and fraud detection preferences:

    ```json theme={null}
    {
      "extraction_config": {
        "enabled": true,
        "schema": {
          // Your schema from step 1
        },
        "extraction_rules": "Extract all invoice details accurately."
      },
      "fraud_config": {
        "enabled": true
      }
    }
    ```
  </Step>

  <Step title="Create the template via API">
    Use the [Create Document Template](/api-reference/endpoint/document-templates-create) endpoint to create your template:

    ```bash theme={null}
    curl -X POST https://api.beltic.com/v1/document-templates \
      -H "X-Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "data": {
          "type": "document-template",
          "attributes": {
            "name": "Invoice Processing Template",
            "description": "Template for processing invoices",
            "extraction_config": {
              "enabled": true,
              "schema": {
                "type": "object",
                "properties": {
                  "invoice_number": {
                    "type": ["string", "null"],
                    "description": "Invoice identifier"
                  },
                  "amount": {
                    "type": ["number", "null"],
                    "description": "Total invoice amount"
                  },
                  "date": {
                    "type": ["string", "null"],
                    "description": "Invoice date"
                  },
                  "vendor": {
                    "type": ["string", "null"],
                    "description": "Vendor name"
                  }
                },
                "required": ["invoice_number", "amount", "date", "vendor"]
              },
              "extraction_rules": "Extract all invoice details accurately."
            },
            "fraud_config": {
              "enabled": true
            }
          }
        }
      }'
    ```

    The response includes the template ID which you'll use when creating documents.
  </Step>
</Steps>

## Listing Templates

Retrieve all available templates using the [List Document Templates](/api-reference/endpoint/document-templates-list) endpoint:

```bash theme={null}
curl -X GET "https://api.beltic.com/v1/document-templates?filter[is_active]=true" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### Filtering Options

* **Active templates only**: `?filter[is_active]=true`
* **Published templates**: `?filter[status]=published`
* **Pagination**: Use `page[size]` to control results per page (default: 15, max: 100)

### Example Response

```json theme={null}
{
  "data": [
    {
      "type": "document-template",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "attributes": {
        "name": "Invoice Processing Template",
        "description": "Template for processing invoices",
        "status": "published",
        "is_active": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "links": {
    "first": "/v1/document-templates?page[after]=...",
    "last": "/v1/document-templates?page[before]=..."
  }
}
```

## Retrieving a Template

Get detailed information about a specific template using the [Get Document Template](/api-reference/endpoint/document-templates-get) endpoint:

```bash theme={null}
curl -X GET https://api.beltic.com/v1/document-templates/{template_id} \
  -H "X-Api-Key: YOUR_API_KEY"
```

The response includes the complete template configuration, including the extraction schema and fraud detection settings.

## Updating a Template

Modify an existing template using the [Update Document Template](/api-reference/endpoint/document-templates-update) endpoint:

```bash theme={null}
curl -X PATCH https://api.beltic.com/v1/document-templates/{template_id} \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "document-template",
      "id": "{template_id}",
      "attributes": {
        "name": "Updated Invoice Template",
        "extraction_config": {
          "schema": {
            // Updated schema
          }
        }
      }
    }
  }'
```

**Note**: Updates to templates only affect new documents created after the update. Documents already in processing will continue using the configuration that was active when they were created.

## Using Templates with Documents

When creating a document, reference a template by providing the `document_template_id`:

```bash theme={null}
curl -X POST https://api.beltic.com/v1/documents \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "document",
      "meta": {
        "document_template_id": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }'
```

The document will automatically use the template's extraction schema and fraud detection configuration.

## Best Practices

<Accordion title="Template Organization">
  * Use descriptive names that clearly indicate the document type (e.g., "Invoice Processing", "Contract Analysis")
  * Include detailed descriptions explaining when to use each template
</Accordion>

<Accordion title="Schema Design">
  * Start with essential fields and expand as needed
  * Use `description` fields to provide context for extraction
  * Remember that fields must be nullable: `"type": ["string", "null"]`
</Accordion>

<Accordion title="Error Handling">
  * Test templates with sample documents before using in production
  * Monitor template usage to identify which templates need updates
</Accordion>