Skip to main content

​
Quickstart

This guide walks through the core Docyard workflow using realistic insurance distribution examples: creating a dock, uploading a declaration page, adding recipients across all four stakeholder types, and configuring access policies.

​
Prerequisites

  • A Docyard API key (get one here)
  • curl installed on your machine

​
Step 1: Create a Dock

A dock is your isolated workspace. Every artifact, recipient, and policy belongs to a dock. 
curl -X POST https://api.docyard.io/v1/docks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meridian Property & Casualty",
    "domain": "meridianpc.com",
    "legalName": "Meridian Property & Casualty Insurance Co.",
    "businessType": "corporation",
    "businessEmail": "[email protected]"
  }'
Response
{
  "id": "dock_01HQ3K...",
  "name": "Meridian Property & Casualty",
  "domain": "meridianpc.com",
  "status": "ACTIVE",
  "domainVerificationStatus": "UNVERIFIED",
  "kycStatus": "NOT_STARTED",
  "createdAt": "2025-01-15T10:30:00.000Z"
}
Save the id — you need it for every subsequent call.

​
Step 2: Upload Artifacts

Upload a declaration page. Docyard computes a SHA-256 hash and deduplicates automatically.
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../artifacts/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"
Response
{
  "id": "art_01HQ3M...",
  "filename": "dec-page-POL-2025-88401.pdf",
  "contentType": "application/pdf",
  "size": 245760,
  "hash": "sha256:a3f8c2d1e4b5...",
  "isDuplicate": false,
  "createdAt": "2025-01-15T10:31:00.000Z"
}
If you upload the same file again, isDuplicate returns true and no additional storage is consumed.

​
Step 3: Add Recipients (All Four Personas)

Add one recipient per stakeholder type to see the full access model.
Two ways to handle identifiers. This quickstart uses Flow A: pre-populated identifiers — you store identifiers when creating the recipient. This is the most common pattern for institutional recipients whose identifiers are known upfront.There’s also Flow B: runtime submission — you create the recipient with just name and email, and the recipient submits their identifiers when they access documents through the portal or API. See How identifiers flow through the system for details.

​
Mortgagee — Bulk API access

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First National Bank",
    "email": "[email protected]",
    "stakeholderClass": "mortgagee",
    "identifiers": {
      "lender_id": "LND-4821",
      "policy_number": "POL-2025-88401"
    }
  }'

​
Agent — Portal + bulk download

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen — Apex Insurance Group",
    "email": "[email protected]",
    "stakeholderClass": "agent",
    "identifiers": {
      "agency_code": "AGN-1192",
      "policy_number": "POL-2025-88401"
    }
  }'

​
Policyholder — Single retrieval via portal

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Whitfield",
    "email": "[email protected]",
    "stakeholderClass": "policyholder",
    "identifiers": {
      "phone": "+1-860-555-0147",
      "date_of_birth": "1983-06-15",
      "policy_number": "POL-2025-88401"
    }
  }'
Alternative: Runtime submission. You can also add a policyholder with just their name and email. They’ll provide date_of_birth and policy_number when they access the portal:
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Whitfield",
    "email": "[email protected]",
    "stakeholderClass": "policyholder"
  }'
The policy’s match.identifiers defines what the recipient must provide at access time. Docyard validates the submitted values against the policy recipe — if they match, access is granted.

​
Auditor — Time-boxed read-only

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deloitte — Maria Gonzalez",
    "email": "[email protected]",
    "stakeholderClass": "auditor",
    "identifiers": {
      "badge_id": "AUD-DT-2025-0042",
      "nda_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  }'

​
Step 4: Create Access Policies

Each persona needs a different policy recipe. Here are two examples — the bulk API access (most common) and the auditor (most restrictive).

​
Mortgagee bulk access policy

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mortgagee Bulk API Access",
    "recipe": "{\"stakeholderClass\":\"mortgagee\",\"artifactTypes\":[\"declaration-page\",\"certificate-of-insurance\"],\"auth\":{\"factors\":[\"shared_passphrase\",\"tls_certificate\"],\"tls\":{\"require_mutual\":true}},\"access\":{\"method\":\"bulk_api\",\"max_batch_size\":10000},\"match\":{\"identifiers\":[\"lender_id\",\"policy_number\"]}}"
  }'

​
Auditor time-boxed policy

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 External Audit",
    "recipe": "{\"stakeholderClass\":\"auditor\",\"artifactTypes\":[\"*\"],\"auth\":{\"factors\":[\"badge_id\",\"nda_hash\"]},\"access\":{\"method\":\"portal\",\"read_only\":true,\"download_enabled\":false},\"match\":{\"identifiers\":[\"badge_id\",\"nda_hash\"]},\"constraints\":{\"time_window\":{\"start\":\"2025-01-15T00:00:00Z\",\"end\":\"2025-02-15T00:00:00Z\"},\"auto_expire\":true}}"
  }'
Publish the bulk access policy to production: 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../policies/pol_01HQ3P.../publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "production" }'

​
Step 5: Generate a Passphrase

The bulk API policy requires a shared passphrase. Generate one for the institutional recipient: 
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First National Bank — API Passphrase",
    "expiresInDays": 90
  }'
Response
{
  "id": "sec_01HQ3T...",
  "secret": "dk_sec_7f2a9b4c1e8d3f6a0b5c2d9e4f7a1b8c",
  "name": "First National Bank — API Passphrase",
  "expiresAt": "2025-04-15T10:32:00.000Z"
}
The secret value is returned only once. Securely transmit it to the recipient. Docyard stores only the SHA-256 hash and cannot recover the plaintext.

​
Step 6: Retrieve via Bulk API

The institutional recipient creates a bulk retrieval job: 
curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "metadata": { "document_type": "declaration-page" },
    "sinceTimestamp": "2025-01-01T00:00:00.000Z"
  }'
Fetch results with signed download URLs:
curl https://api.docyard.io/v1/retrieval/jobs/job_01HQ3Q.../results \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "status": "COMPLETED",
  "totalCount": 1,
  "items": [
    {
      "artifactId": "art_01HQ3M...",
      "filename": "dec-page-POL-2025-88401.pdf",
      "url": "https://storage.docyard.io/signed/...",
      "expiresAt": "2025-01-15T11:34:00.000Z"
    }
  ]
}
Signed URLs expire after 1 hour. Result sets expire after 24 hours. Download artifacts promptly.

​
Next Steps