Skip to main content

​
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:
TypeExample
Insurance CarriersUpload declaration pages, endorsements
PlatformsHarmony, SAM - upload on behalf of carriers
Title CompaniesUpload closing documents, deeds
Healthcare ProvidersUpload EOBs, lab results
Government AgenciesUpload permits, certificates

​
Distributor Onboarding

​
Step 1: Sign Up

Provide basic information: 
{
  "organization_name": "Acme Insurance",
  "business_email": "[email protected]",
  "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: 
POST /api/v1/upload endpoints
{
  "name": "Production Upload",
  "description": "Main upload endpoint"
}

​
Step 4: Receive Credentials

Get API keys for authentication: 
{
  "upload endpoint_id": "upload endpoint-abc123",
  "api_key": "dk_live_xxxxxxxxxxxx",
  "api_secret": "dk_secret_xxxxxxxxxxxx"
}

​
Distributor Workflow

​
1. Create Artifact Type Templates

Before uploading, create or select artifact type templates: 
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: 
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: 
GET /api/v1/upload/artifacts?status=active&limit=100

{
  "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: 
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: 
{
  "locks": {
    "policy_number": { "weight": 30 },
    "effective_date": { "weight": 20 },
    "mortgagee_name": { "weight": 10 }
  },
  "threshold": 50
}
Requires multiple strong keys. Easy Access: 
{
  "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: 
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: 
POST /api/v1/upload endpoints/upload endpoint-abc123/rotate-keys

{
  "new_api_key": "dk_live_yyyyyyyyyyyy",
  "new_api_secret": "dk_secret_yyyyyyyyyyyy",
  "old_key_expires_at": "2026-03-16T10:30:00Z"
}

​
Rate Limits

ActionLimit
Upload (single)100/minute
Upload (batch)10 batches/minute
List artifacts300/minute
Revoke artifacts50/minute

​
Audit Trail

All distributor actions are logged: 
{
  "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
  • Learn about [Uploads](/concepts/upload endpoints-and-docks)
  • See the [API Reference](/api-reference/upload endpoints)