Skip to main content

​
Recipient Onboarding

Recipients are the parties authorized to retrieve artifacts from your dock. This guide covers onboarding for each stakeholder persona, group management, and secret configuration.

​
Identifier Strategies

Before onboarding, decide how identifiers will reach the policy engine for each persona:
StrategyWhen to UseBest For
Pre-populatedIdentifiers are known at registration timeMortgagees, agents, auditors
Runtime submissionRecipients provide identifiers when accessing documentsPolicyholders, self-service portals
HybridStore some identifiers (e.g., phone for OTP), let others be submitted at access timePolicyholders with partial data
The identifiers field is always optional when creating a recipient. The policy’s match.identifiers defines what’s required for access — values can come from the stored record, runtime submission, or both. See Identifier Resolution for how the policy engine merges both sources.

​
Persona-Based Onboarding

Each stakeholder type has different identifiers and authentication requirements. Register recipients with the correct stakeholderClass and identifiers so that policies can target them precisely.

​
Mortgagee — Institutional Lenders

Mortgagees access documents via bulk API with shared passphrase + mutual TLS. 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -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"
    }
  }'
After registration, generate a shared passphrase and provide the mortgagee with their mutual TLS certificate configuration.

​
Agent — Insurance Agencies

Agents access documents through the branded portal or bulk download, authenticated via WebAuthn. 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -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"
    }
  }'
Agents register their WebAuthn credential (FIDO2 security key or device biometric) during their first portal login.

​
Policyholder — Insured Individuals

Policyholders retrieve their own documents through the self-service portal with SMS OTP verification.
Option A: Pre-populate all identifiers (when data is available at registration):
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -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"
    }
  }'
Option B: Runtime submission (policyholder submits identifiers at the portal):
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Whitfield",
    "email": "[email protected]",
    "stakeholderClass": "policyholder",
    "identifiers": {
      "phone": "+1-860-555-0147"
    }
  }'
In Option B, only phone is stored (needed for OTP delivery). When the policyholder accesses the portal, they submit date_of_birth and policy_number. The policy engine merges the stored phone with the submitted values, validates them against the recipe, and grants access.
Even with runtime submission, storing the phone identifier is recommended — the SMS OTP factor needs a delivery target before the policyholder can authenticate.

​
Auditor — Time-Boxed External Access

Auditors get temporary, read-only access that automatically expires. The NDA hash ensures a signed non-disclosure agreement is on file. 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -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:e3b0c44298fc1c149afbf4c8996fb924..."
    }
  }'
Compute the NDA hash by running sha256sum on the signed NDA PDF before registering the auditor. The policy engine validates this hash at retrieval time — if the NDA is updated, the hash must be re-registered.

​
Batch Onboarding

​
Batch API

Create multiple recipients of mixed persona types in one call: 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients/batch \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "name": "First National Bank",
        "email": "[email protected]",
        "stakeholderClass": "mortgagee",
        "identifiers": { "lender_id": "LND-4821", "policy_number": "POL-2025-88401" }
      },
      {
        "name": "Citywide Credit Union",
        "email": "[email protected]",
        "stakeholderClass": "mortgagee",
        "identifiers": { "lender_id": "LND-7733", "policy_number": "POL-2025-88401" }
      },
      {
        "name": "Sarah Chen — Apex Insurance Group",
        "email": "[email protected]",
        "stakeholderClass": "agent",
        "identifiers": { "agency_code": "AGN-1192", "policy_number": "POL-2025-88401" }
      },
      {
        "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" }
      }
    ]
  }'
Failed items do not block successful ones — check the errors array for per-item failures.

​
CSV Import

For large catalogs, upload a CSV file: 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients/import/csv \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -F "[email protected]"
Example CSV: 
name,email,stakeholder_class,lender_id,agency_code,phone,policy_number
First National Bank,[email protected],mortgagee,LND-4821,,,POL-2025-88401
Citywide Credit Union,[email protected],mortgagee,LND-7733,,,POL-2025-88401
Sarah Chen — Apex Insurance,[email protected],agent,,AGN-1192,,POL-2025-88401
James Whitfield,[email protected],policyholder,,,+1-860-555-0147,POL-2025-88401

​
Organizing Into Groups

Create groups by persona type for bulk policy assignment: 
# Mortgagee group
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../groups \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mortgagee Partners",
    "description": "All institutional mortgage lender recipients",
    "recipientIds": ["rcp_01HQ3N...", "rcp_01HQ3P..."]
  }'

# Auditor group (for Q1 audit engagement)
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../groups \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 Audit Team",
    "description": "Deloitte external audit — engagement #DT-2025-001",
    "recipientIds": ["rcp_01HQ3R..."]
  }'
Assign a policy to the group — all members inherit the access rules: 
curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../groups/grp_01HQ3R.../assign-policy \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "policyId": "pol_01HQ3P..." }'

​
Generating Passphrase Secrets

Mortgagees authenticate with a shared passphrase. Generate one after registration: 
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First National Bank — Bulk API Passphrase",
    "expiresInDays": 90
  }'
Response
{
  "id": "sec_01HQ3T...",
  "secret": "dk_sec_7f2a9b4c1e8d3f6a0b5c2d9e4f7a1b8c",
  "name": "First National Bank — Bulk API Passphrase",
  "expiresAt": "2025-04-15T10:32:00.000Z"
}
The secret value is returned only once. Transmit it to the mortgagee through a secure channel (e.g., encrypted email, secure portal). Docyard stores only the SHA-256 hash.

​
Rotating Passphrases

Rotate before expiration to maintain uninterrupted access: 
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets/sec_01HQ3T.../rotate \
  -H "Authorization: Bearer dk_live_a1b2c3d4..."
The old passphrase is marked ROTATED and a new one is issued. Communicate the new passphrase to the mortgagee and allow a grace period for the transition.

​
Revoking Secrets

Immediately invalidate a compromised passphrase: 
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets/sec_01HQ3T.../revoke \
  -H "Authorization: Bearer dk_live_a1b2c3d4..."

​
Next Steps