> ## 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.

# Insurance Industry

> Using Docyard for insurance document distribution

# Insurance Industry Guide

This guide covers how insurance carriers and their partners use Docyard.

## Overview

Insurance involves multiple parties exchanging high-value documents:

* **Carriers** create and distribute declaration pages, endorsements, renewals
* **Mortgage lenders** need declarations for loans
* **Agents** need policy documents for sales and service
* **Policyholders** need documents for claims and reference

Docyard provides a single lake where all these parties connect once and share documents freely.

## Key Document Types

### Declaration Pages

<details>
  <summary>👆 Click to expand: Insurance Declaration Flow Diagram</summary>

  ```mermaid theme={null}
  sequenceDiagram
      participant CARRIER as Insurance Carrier<br/>(Distributor)
      participant LAKE as The Lake
      participant LENDER as Mortgage Lender<br/>(Collector)

      Note over CARRIER,LENDER: INSURANCE DECLARATION FLOW

      CARRIER->>CARRIER: 1. Create declaration PDF
      CARRIER->>CARRIER: 2. Assign metadata<br/>policy_number: POL-123<br/>mortgagee: FirstCity Bank

      CARRIER->>LAKE: 3. Upload via Upload
      Note right of CARRIER: template: Declaration Page<br/>threshold: 25

      LAKE-->>CARRIER: Artifact stored

      Note over LENDER: Later...
      LENDER->>LAKE: 4. Search for declarations<br/>mortgagee: FirstCity Bank
      LAKE-->>LENDER: Found 150 declarations

      LENDER->>LAKE: 5. Present key<br/>policy_number: POL-123
      LAKE->>LAKE: Calculate: 25 >= 25 ✓

      LAKE-->>LENDER: 6. Access Granted!<br/>Download declaration PDF
  ```
</details>

### Declaration Pages

The most common insurance document. Contains:

* Policy number
* Effective and expiration dates
* Coverage details
* Mortgagee information

**Lock Strategy:**

| Lock               | Weight | Rationale                              |
| ------------------ | ------ | -------------------------------------- |
| `policy_number`    | 25     | Primary identifier, unique to carrier  |
| `effective_date`   | 10     | Broad, but confirms timing             |
| `mortgagee_name`   | 5      | Known to those with insurable interest |
| `property_address` | 5      | Known to those with insurable interest |

**Threshold**: 25 (policy number alone grants access)

### Endorsements

Policy modifications. Contains:

* Policy number (linked)
* Endorsement number
* Change description
* Effective date

**Lock Strategy:**

| Lock                 | Weight | Rationale                |
| -------------------- | ------ | ------------------------ |
| `policy_number`      | 20     | Links to original policy |
| `endorsement_number` | 15     | Specific to this change  |
| `effective_date`     | 5      | Timing                   |

**Threshold**: 20

### Renewal Notices

Policy renewal notifications. Contains:

* Policy number
* Renewal date
* New premium
* Expiration of current policy

## Distributor Setup (Insurance Carriers)

### Step 1: Sign Up and Verify

```bash theme={null}
curl -X POST https://api.docyard.io/v1/auth/signup/distributor \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "Acme Insurance",
    "business_email": "ops@acme-insurance.com",
    "industry": "insurance",
    "website": "https://acme-insurance.com"
  }'
```

Submit verification documents:

* State insurance license
* Tax ID / EIN
* Proof of business address

### Step 2: Create Artifact Type Templates

Create templates for your document types:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/templates \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Declaration Page",
    "description": "Acme standard insurance declaration document",
    "locks": [
      {
        "name": "policy_number",
        "data_type": "string",
        "description": "Acme policy number",
        "validation": { "pattern": "^ACME-[0-9]{8}$" },
        "weight": 25,
        "required": true
      },
      {
        "name": "effective_date",
        "data_type": "date",
        "weight": 10,
        "required": true
      },
      {
        "name": "mortgagee_name",
        "data_type": "string",
        "weight": 5,
        "required": false
      },
      {
        "name": "property_address",
        "data_type": "string",
        "weight": 5,
        "required": false
      }
    ]
  }'
```

### Step 3: Upload Documents

Nightly batch upload of declarations:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/artifacts/batch \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_id": "acme-declarations-2026-03-15",
    "artifacts": [
      {
        "idempotency_key": "ACME-00000001-2026-03-15",
        "template_id": "tmpl-acme-dec-001",
        "locks": {
          "policy_number": { "value": "ACME-00000001" },
          "effective_date": { "value": "2026-03-15" },
          "mortgagee_name": { "value": "FirstCity Bank" }
        },
        "threshold": 25
      }
    ]
  }'
```

## Collector Setup (Mortgage Lenders)

### Step 1: Sign Up and Complete KYC

```bash theme={null}
curl -X POST https://api.docyard.io/v1/auth/signup/collector \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "FirstCity Bank",
    "business_email": "operations@firstcitybank.com",
    "industry": "mortgage_lending"
  }'
```

Submit KYC documents:

* Bank charter / license
* NMLS ID
* Tax ID

### Step 2: Declare Keys

Mortgage lenders have access to:

* Policy numbers (received from carriers)
* Loan numbers (internal)
* Mortgagee names (their portfolio)

```bash theme={null}
curl -X POST https://api.docyard.io/v1/collectors/coll-xyz789/declare-keys \
  -H "Content-Type: application/json" \
  -d '{
    "declared_locks": [
      "policy_number",
      "loan_number",
      "mortgagee_name",
      "effective_date"
    ],
    "declaration_notes": "Policy numbers received via nightly carrier feeds. Loan numbers from our LOS. Mortgagee names from loan portfolio."
  }'
```

### Step 3: Retrieve Declarations

Search and retrieve declarations for your portfolio:

```bash theme={null}
# Search for declarations
curl -X POST https://api.docyard.io/v1/dock/search \
  -H "X-API-Key: dk_live_coll_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "document_type": "declaration_page",
      "mortgagee_name": "FirstCity Bank",
      "effective_date_after": "2026-01-01"
    }
  }'
```

```bash theme={null}
# Retrieve with your keys
curl -X POST https://api.docyard.io/v1/dock/retrieve/batch \
  -H "X-API-Key: dk_live_coll_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_ids": ["art-001", "art-002", "art-003"],
    "keys": {
      "policy_number": "ACME-00000001"
    }
  }'
```

## Integration Patterns

### Nightly Batch Upload (Carriers)

```javascript theme={null}
async function uploadNightlyDeclarations() {
  // 1. Generate manifest from policy system
  const manifest = await policySystem.getDeclarationsForUpload();
  
  // 2. Create batch upload
  const batch = await client.upload endpoint.uploadBatch({
    manifest_id: `declarations-${today}`,
    artifacts: manifest.map(p => ({
      idempotency_key: `${p.policy_number}-${today}`,
      template_id: 'tmpl-acme-dec-001',
      locks: {
        policy_number: { value: p.policy_number },
        effective_date: { value: p.effectiveDate },
        mortgagee_name: { value: p.mortgagee }
      },
      threshold: 25
    }))
  });
  
  // 3. Log results
  console.log(`Uploaded ${batch.succeeded} declarations`);
}
```

### Nightly Batch Retrieval (Lenders)

```javascript theme={null}
async function retrieveNightlyDeclarations() {
  // 1. Search for new declarations since last check
  const results = await client.dock.search({
    filters: {
      mortgagee_name: 'FirstCity Bank',
      created_after: lastSyncTime
    }
  });
  
  if (results.length === 0) return;
  
  // 2. Create async retrieval job
  const job = await client.dock.retrieveAsync({
    artifact_ids: results.map(r => r.id),
    keys: { mortgagee_name: 'FirstCity Bank' },
    notify_url: 'https://your-server.com/webhook/docyard'
  });
  
  // 3. Update sync time
  lastSyncTime = new Date().toISOString();
}
```

## Data Flow Example

```
1. Acme Insurance writes new policy
   └── Generates declaration PDF
   └── Uploads to Docyard vian upload endpoint
       └── Template: Acme Declaration Page
       └── Locks: policy_number=ACME-123, mortgagee=FirstCity Bank
       └── Artifact stored in lake

2. FirstCity Bank wants declaration
   └── Searches lake: mortgagee_name="FirstCity Bank"
   └── Finds artifact
   └── Presents keys: mortgagee_name="FirstCity Bank" (score: 5 < 25)
   └── Score too low - needs policy number

3. FirstCity Bank has policy number from carrier feed
   └── Presents keys: policy_number="ACME-123" (score: 25 ≥ 25)
   └── Access granted
   └── Downloads declaration
```

## Benefits

### For Carriers

* **Single upload** → Reaches all collectors
* **No per-customer integrations**
* **Automatic key-based access control**
* **Audit trail of all retrievals**

### For Collectors

* **Single connection** → Access all carriers
* **No calling carriers for documents**
* **Automated retrieval with key feeds**
* **Consistent document format**

***

## Next Steps

* **\[First Upload Setup]\(/guides/first-upload endpoint)** - Configure your upload endpoint
* **[Creating Artifact Types](/guides/creating-artifact-types)** - Design templates
* **[Collector Onboarding](/guides/collector-onboarding)** - Set up collector access
* **[API Reference](/api-reference/overview)** - Full API documentation