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

# Creating Artifact Types

> Design templates for your document types

# Creating Artifact Types

Artifact type templates define the structure of documents you upload. This guide shows you how to create effective templates.

## What is an Artifact Type?

An artifact type is a template that specifies:

* **What locks** (metadata fields) are required/optional
* **Data types** for each lock
* **Validation rules** (patterns, formats)
* **Default weights** for access control

## Template Structure

```json theme={null}
{
  "name": "Template Name",
  "description": "What this document is",
  "locks": [
    {
      "name": "field_name",
      "data_type": "string|number|date|boolean",
      "description": "What this field represents",
      "validation": { ... },
      "weight": 20,
      "required": true
    }
  ]
}
```

## Example: Insurance Declaration Page

Let's create a template for insurance declaration pages:

### Step 1: Define the Template

```bash theme={null}
curl -X POST https://api.docyard.io/v1/templates \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Declaration Page",
    "description": "Standard insurance policy declaration document containing coverage details",
    "locks": [
      {
        "name": "policy_number",
        "data_type": "string",
        "description": "Unique insurance policy identifier",
        "validation": {
          "pattern": "^POL-[0-9]{8}$",
          "min_length": 12,
          "max_length": 12
        },
        "weight": 20,
        "required": true
      },
      {
        "name": "effective_date",
        "data_type": "date",
        "description": "Date the policy coverage begins",
        "weight": 10,
        "required": true
      },
      {
        "name": "expiration_date",
        "data_type": "date",
        "description": "Date the policy coverage ends",
        "weight": 5,
        "required": true
      },
      {
        "name": "mortgagee_name",
        "data_type": "string",
        "description": "Name of the lender/mortgagee",
        "validation": {
          "min_length": 2,
          "max_length": 100
        },
        "weight": 5,
        "required": false
      },
      {
        "name": "property_address",
        "data_type": "string",
        "description": "Insured property address",
        "weight": 5,
        "required": false
      },
      {
        "name": "coverage_amount",
        "data_type": "number",
        "description": "Policy coverage amount in dollars",
        "weight": 3,
        "required": false
      }
    ]
  }'
```

### Step 2: Review Template Before Submitting

List your templates to verify:

```bash theme={null}
curl -X GET https://api.docyard.io/v1/templates \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
```

**Response:**

```json theme={null}
{
  "templates": [
    {
      "template_id": "tmpl-ins-dec-001",
      "name": "Insurance Declaration Page",
      "status": "pending_approval",
      "locks_count": 6,
      "required_locks_count": 3
    }
  ]
}
```

### Step 3: Wait for Approval

Templates go through admin review. You'll receive an email once approved.

## Lock Type Best Practices

### 1. Use Descriptive Names

**Good:**

```json theme={null}
{ "name": "policy_number" }
{ "name": "mortgagee_name" }
```

**Bad:**

```json theme={null}
{ "name": "pn" }
{ "name": "mname" }
```

### 2. Choose Appropriate Data Types

| Data                  | Use       |
| --------------------- | --------- |
| Policy numbers, names | `string`  |
| Dates                 | `date`    |
| Amounts, counts       | `number`  |
| Yes/no flags          | `boolean` |

### 3. Set Realistic Weights

Consider what makes a document "yours":

| Lock Type        | Weight | Rationale             |
| ---------------- | ------ | --------------------- |
| `policy_number`  | 20-30  | Only you issue these  |
| `effective_date` | 5-10   | Date ranges are broad |
| `mortgagee_name` | 5-10   | Others may know this  |

### 4. Mark True Identifiers as Required

```json theme={null}
{
  "name": "policy_number",
  "required": true,
  "weight": 20
}
```

Required fields ensure minimum identification.

## Weight Strategy Examples

### High Security (Threshold: 35)

```json theme={null}
{
  "locks": {
    "policy_number": { "weight": 20 },
    "effective_date": { "weight": 10 },
    "mortgagee_name": { "weight": 5 }
  },
  "threshold": 35
}
```

Collector needs 2+ keys to access.

### Medium Security (Threshold: 20)

```json theme={null}
{
  "locks": {
    "policy_number": { "weight": 20 },
    "effective_date": { "weight": 10 },
    "mortgagee_name": { "weight": 5 }
  },
  "threshold": 20
}
```

Collector needs just the policy number.

### Low Security (Threshold: 10)

```json theme={null}
{
  "locks": {
    "policy_number": { "weight": 20 },
    "effective_date": { "weight": 10 }
  },
  "threshold": 10
}
```

Anyone with one key can access.

## Validation Patterns

### Policy Number

```json theme={null}
{
  "pattern": "^POL-[0-9]{8}$"
}
```

Matches: `POL-12345678`\
Doesn't match: `POL-123`, `POL12345678`

### Date Format

Dates should use ISO 8601 format: `YYYY-MM-DD`

```json theme={null}
{
  "data_type": "date"
}
```

### Numeric Ranges

```json theme={null}
{
  "min": 0,
  "max": 10000000
}
```

## Template Lifecycle

```
draft ──► pending_approval ──► published ──► deprecated
  │              │                   │            │
  │              │                   │            │
  ▼              ▼                   ▼            ▼
Create      Awaiting            Live &        No new
template    review              usable        uploads
```

### Updating Published Templates

You can update draft templates, but published templates are locked:

```bash theme={null}
curl -X PUT https://api.docyard.io/v1/templates/tmpl-ins-dec-001 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Declaration Page v2",
    "description": "Updated with additional fields"
  }'
```

**Response:**

```json theme={null}
{
  "error": "template_locked",
  "message": "Cannot update published template. Create a new version."
}
```

For major changes, create a new template version.

## Common Insurance Template Examples

### Declaration Page

```json theme={null}
{
  "name": "Insurance Declaration Page",
  "locks": ["policy_number", "effective_date", "mortgagee_name", "property_address"]
}
```

### Endorsement

```json theme={null}
{
  "name": "Insurance Endorsement",
  "locks": ["policy_number", "effective_date", "endorsement_type", "change_description"]
}
```

### Renewal Notice

```json theme={null}
{
  "name": "Insurance Renewal Notice",
  "locks": ["policy_number", "renewal_date", "premium_amount", "expiration_date"]
}
```

## Troubleshooting

### Template Rejected

```json theme={null}
{
  "status": "rejected",
  "feedback": "The validation pattern for policy_number is too restrictive. Consider using min_length instead."
}
```

**Solution**: Update the template with the suggested changes and resubmit.

### Template Pending Long Time

If approval takes more than 48 hours, contact support:

```
support@docyard.io
```

Include your template ID.

***

## Next Steps

* **[Artifact Ingestion](/guides/artifact-ingestion)** - Upload strategies
* **\[First Upload Setup]\(/guides/first-upload endpoint)** - Set up your upload endpoint
* **[API Reference](/api-reference/artifact-types)** - Full template API