Skip to main content

​
Recipients

A recipient is any party authorized to retrieve artifacts from a dock. Recipients range from individual policyholders to institutional mortgage lenders — each with tailored authentication and access patterns.

​
Stakeholder Personas

Docyard’s access model is built around four primary stakeholder types, each with distinct identification, authentication, and retrieval patterns:

​
Mortgagee (Institutional)

Mortgage lenders and servicers who need bulk access to declaration pages and certificates of insurance.
PropertyValue
IdentifiersLender ID + policy number
AuthenticationShared passphrase + mutual TLS certificate
Access methodBulk API (thousands of documents per job)
Typical artifactsDeclaration pages, COIs, endorsements
{
  "name": "First National Bank",
  "email": "[email protected]",
  "stakeholderClass": "mortgagee",
  "identifiers": {
    "lender_id": "LND-4821",
    "policy_number": "POL-2025-88401"
  }
}

​
Agent (Agency)

Insurance agents and agency staff who access client documents through the portal or bulk download.
PropertyValue
IdentifiersAgency code + policy number
AuthenticationWebAuthn challenge (FIDO2 security key or biometric)
Access methodPortal (single document) or bulk download
Typical artifactsDec pages, policy packets, endorsements, renewal notices
{
  "name": "Sarah Chen — Apex Insurance Group",
  "email": "[email protected]",
  "stakeholderClass": "agent",
  "identifiers": {
    "agency_code": "AGN-1192",
    "policy_number": "POL-2025-88401"
  }
}

​
Policyholder (Individual)

The insured individual retrieving their own policy documents through the self-service portal.
PropertyValue
IdentifiersEmail or phone + date of birth
AuthenticationSMS OTP verification
Access methodSingle document retrieval via portal
Typical artifactsTheir own declaration page, ID cards, renewal notices
{
  "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"
  }
}

​
Auditor (Time-Boxed)

External or internal auditors with temporary, read-only access that automatically expires.
PropertyValue
IdentifiersBadge ID + NDA document hash
AuthenticationBadge ID verification + NDA hash validation
Access methodRead-only access within a time-boxed window
Typical artifactsAll artifacts in scope, audit logs
{
  "name": "Deloitte — Maria Gonzalez",
  "email": "[email protected]",
  "stakeholderClass": "auditor",
  "identifiers": {
    "badge_id": "AUD-DT-2025-0042",
    "nda_hash": "sha256:e3b0c44298fc1c14..."
  }
}
Auditor access is time-boxed by policy. When the access window expires, retrieval is automatically denied — no manual revocation needed. The NDA hash ensures the correct non-disclosure agreement is on file before access is granted.

​
Identifiers

Recipients carry custom key-value identifiers that link them to external systems. These identifiers are indexed and searchable, enabling policy routing based on external business keys. Common identifier patterns:
IdentifierUsed ByPurpose
lender_idMortgageeLinks to lender’s internal system
policy_numberAllAssociates recipient with specific policy
agency_codeAgentLinks to agency management system
phonePolicyholderSMS OTP delivery target
date_of_birthPolicyholderIdentity verification factor
badge_idAuditorAudit firm credential reference
nda_hashAuditorSHA-256 hash of signed NDA document

​
Identifier Resolution

There are two ways identifiers reach the policy engine — both are valid, and which you use depends on the persona and your integration pattern. Flow A: Pre-populated at registration. Store identifiers when creating the recipient. At access time, the policy engine matches the stored values against the recipe’s match.identifiers. This is the typical pattern for institutional recipients whose identifiers are known upfront: 
1. Create recipient with identifiers (lender_id, policy_number)
2. Create policy with match.identifiers: ["lender_id", "policy_number"]
3. Recipient authenticates → policy matches stored identifiers → access granted
Best for: Mortgagees and agents, whose lender IDs, agency codes, and policy numbers are known at onboarding time. Flow B: Runtime submission. Create the recipient with just name and email (and optionally stakeholderClass). The recipient submits identifiers when accessing documents through the portal or API. The policy engine validates the submitted values against the recipe: 
1. Create recipient with name + email only
2. Create policy with match.identifiers: ["email", "date_of_birth", "policy_number"]
3. Recipient accesses portal → submits DOB + policy number → policy validates → access granted
Best for: Policyholders, who verify identity interactively at access time. Also useful when identifiers aren’t available at registration (e.g., bulk-imported contacts who self-serve later). Hybrid. You can pre-populate some identifiers and require others at runtime. For example, store a policyholder’s phone (needed for OTP delivery) but let them submit date_of_birth and policy_number when they access the portal. The policy engine merges stored and submitted identifiers before evaluating the recipe.
The identifiers field on a recipient is always optional. The policy’s match.identifiers defines what’s required — not the recipient record. If an identifier is missing from both the stored record and the runtime submission, the policy evaluation fails and access is denied.

​
Recipient Groups

Organize recipients into groups for bulk policy assignment. When a policy is assigned to a group, every member inherits the access rules:
  • Add or remove members without modifying individual policies
  • Assign a single policy to hundreds of recipients at once
  • Groups can overlap — a recipient can belong to multiple groups
Example groups: mortgagee-partners, agency-network, q1-audit-team.

​
Docyard Identity

Docyard Identity is a cross-dock credential system. Recipients who verify their identity for one dock can use the same verified identity for other docks — no re-verification needed. This creates network effects: the more docks a recipient interacts with, the faster subsequent onboarding becomes. A mortgagee verified on one carrier’s dock can access another carrier’s dock without re-submitting TLS certificates.

​
Secrets

Recipients can have shared secrets for authentication — particularly useful for the mortgagee passphrase flow:
  • Generated as 32-byte random values
  • Stored as SHA-256 hashes (the plaintext is returned only once)
  • Rotatable and revocable
  • Optionally time-limited (e.g., auditor access windows)

​
Batch Operations

MethodDescription
Batch createCreate multiple recipients in a single API call
CSV importUpload a CSV file with recipient data
Both methods include per-row error reporting — failed items don’t block successful ones.