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

# Distributors

> Entities that upload artifacts to the lake

# Distributors

Distributors are entities that create and upload artifacts into the lake. They use **upload endpoints** to drop artifacts.

## Who Can Be a Distributor?

Anyone who creates documents and wants to distribute them through Docyard:

| Type                     | Example                                     |
| ------------------------ | ------------------------------------------- |
| **Insurance Carriers**   | Upload declaration pages, endorsements      |
| **Platforms**            | Harmony, SAM - upload on behalf of carriers |
| **Title Companies**      | Upload closing documents, deeds             |
| **Healthcare Providers** | Upload EOBs, lab results                    |
| **Government Agencies**  | Upload permits, certificates                |

## Distributor Onboarding

### Step 1: Sign Up

Provide basic information:

```json theme={null}
{
  "organization_name": "Acme Insurance",
  "business_email": "ops@acme-insurance.com",
  "industry": "insurance",
  "website": "https://acme-insurance.com"
}
```

### Step 2: Business Verification

Submit verification documents:

* Business license
* Tax ID / EIN
* Proof of address
* Industry-specific credentials (if applicable)

### Step 3: Upload Setup

Create your upload endpoint for uploading artifacts:

```json theme={null}
POST /api/v1/upload endpoints
{
  "name": "Production Upload",
  "description": "Main upload endpoint"
}
```

### Step 4: Receive Credentials

Get API keys for authentication:

```json theme={null}
{
  "upload endpoint_id": "upload endpoint-abc123",
  "api_key": "dk_live_xxxxxxxxxxxx",
  "api_secret": "dk_secret_xxxxxxxxxxxx"
}
```

## Distributor Workflow

<details>
  <summary>👆 Click to expand: Distributor Document Ingestion Journey</summary>

  ```mermaid theme={null}
  sequenceDiagram
      participant D as Distributor
      participant API as Docyard API
      participant T as Template Registry
      participant L as The Lake

      Note over D,L: DISTRIBUTOR DOCUMENT INGESTION JOURNEY

      D->>API: 1. Create artifact type template
      API->>T: Store template
      T-->>D: Template created (draft)

      D->>API: 2. Submit template for review
      API->>T: Update status to pending_approval
      T-->>D: Submitted for admin review

      Note over D: Admin reviews and approves...

      D->>API: 3. Upload artifact with template
      D->>API: POST /upload endpoint/artifacts
      Note right of D: - template_id<br/>- locks (keys & weights)<br/>- threshold<br/>- content
      API->>L: Store artifact in lake
      L-->>D: Artifact uploaded (active)

      loop Nightly Batch
          D->>API: Upload batch of artifacts
          API->>L: Store batch in lake
          L-->>D: Batch uploaded successfully
      end
  ```
</details>

### 1. Create Artifact Type Templates

Before uploading, create or select artifact type templates:

```json theme={null}
POST /api/v1/templates
{
  "name": "Acme Declaration Page",
  "description": "Our standard declaration page format",
  "locks": [
    {
      "name": "policy_number",
      "data_type": "string",
      "weight": 20,
      "required": true
    },
    {
      "name": "effective_date",
      "data_type": "date",
      "weight": 10,
      "required": true
    }
  ]
}
```

### 2. Upload Artifacts

Use your upload endpoint to upload:

```json theme={null}
POST /api/v1/upload/artifacts
{
  "template_id": "uuid-of-template",
  "locks": {
    "policy_number": { "value": "POL-12345678" },
    "effective_date": { "value": "2026-03-15" }
  },
  "threshold": 20,
  "content": "<pdf-data>"
}
```

### 3. Monitor & Manage

Track your artifacts:

```json theme={null}
GET /api/v1/upload/artifacts?status=active&limit=100
```

```json theme={null}
{
  "artifacts": [
    {
      "id": "art-abc123",
      "template": "Acme Declaration Page",
      "locks": { "policy_number": "POL-12345678" },
      "status": "active",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ]
}
```

### 4. Revoke if Needed

Remove access to specific artifacts:

```json theme={null}
DELETE /api/v1/upload/artifacts/art-abc123
```

## Distributor Responsibilities

### Access Control Design

Distributors define:

1. **Which lock types to use** - Choose relevant metadata fields
2. **Weight assignments** - How important is each lock
3. **Threshold scores** - How hard should it be to access

### Example Weight Strategies

**High Security:**

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

Requires multiple strong keys.

**Easy Access:**

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

Single key grants access.

### Consistency

Use artifact type templates to ensure:

* All declaration pages have the same locks
* Lock names are consistent across uploads
* Weights follow your security policy

## Platform Distributors

Platforms like Harmony act as distributors on behalf of multiple carriers.

### How It Works

1. **Platform creates one upload endpoint**
2. **Each carrier configures their templates**
3. **Platform uploads artifacts with carrier-specific locks**

### Example

```
Platform Upload: upload endpoint-harmony-001

Carrier: Acme Insurance
└── Template: "Acme Declaration"
    └── Locks: policy_number, effective_date

Carrier: Best Insurance
└── Template: "Best Declaration"
    └── Locks: policy_id, effective_dt, insured_name
```

The platform doesn't need separate upload endpoints per carrier - they all use the same upload endpoint with different templates.

## Authentication

Distributors authenticate using API keys:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/artifacts \
  -H "X-API-Key: dk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: dk_secret_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### Key Rotation

Rotate keys regularly for security:

```json theme={null}
POST /api/v1/upload endpoints/upload endpoint-abc123/rotate-keys
```

```json theme={null}
{
  "new_api_key": "dk_live_yyyyyyyyyyyy",
  "new_api_secret": "dk_secret_yyyyyyyyyyyy",
  "old_key_expires_at": "2026-03-16T10:30:00Z"
}
```

## Rate Limits

| Action           | Limit             |
| ---------------- | ----------------- |
| Upload (single)  | 100/minute        |
| Upload (batch)   | 10 batches/minute |
| List artifacts   | 300/minute        |
| Revoke artifacts | 50/minute         |

## Audit Trail

All distributor actions are logged:

```json theme={null}
{
  "event": "artifact_uploaded",
  "upload endpoint_id": "upload endpoint-abc123",
  "distributor_id": "dist-xyz789",
  "artifact_id": "art-123abc",
  "timestamp": "2026-03-15T10:30:00Z",
  "locks": { "policy_number": "POL-12345678" }
}
```

***

## Next Steps

* Understand [Artifact Types](/concepts/artifact-types)
* Learn about \[Uploads]\(/concepts/upload endpoints-and-docks)
* See the \[API Reference]\(/api-reference/upload endpoints)