Create a Recipient

Adds a new recipient — an authorized party who can retrieve artifacts from this dock. Include stakeholderClass and identifiers appropriate to the recipient’s persona.

POST /v1/docks/:dockId/recipients

Path Parameters

Parameter	Type	Description
`dockId`	string	The dock ID

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Recipient display name
`email`	string	Required	Recipient email (stored lowercase)
`stakeholderClass`	string	Optional	Persona type: `mortgagee`, `agent`, `policyholder`, `auditor`
`identifiers`	object	Optional	Persona-specific key-value identifiers (see below)

Persona Identifier Patterns

Insurance
Real Estate
Healthcare
Financial Services

Persona	Key Identifiers	Auth Model
`mortgagee`	`lender_id`, `policy_number`	Shared passphrase + mTLS cert
`agent`	`agency_code`, `policy_number`	WebAuthn challenge
`policyholder`	`email`, `phone`, `date_of_birth`, `policy_number`	SMS OTP
`auditor`	`badge_id`, `nda_hash`	Badge + NDA validation, time-boxed

Persona	Key Identifiers	Auth Model
`mortgagee`	`lender_id`, `file_number`	Shared passphrase + mTLS cert
`agent`	`agent_license`, `file_number`	WebAuthn challenge
`policyholder`	`email`, `phone`, `date_of_birth`, `file_number`	SMS OTP
`auditor`	`badge_id`, `nda_hash`	Badge + NDA validation, time-boxed

Persona	Key Identifiers	Auth Model
`mortgagee`	`payer_id`, `member_id`	Shared passphrase + mTLS cert
`agent`	`npi_number`, `member_id`	WebAuthn challenge
`policyholder`	`email`, `phone`, `date_of_birth`, `member_id`	SMS OTP
`auditor`	`badge_id`, `nda_hash`	Badge + NDA validation, time-boxed

Persona	Key Identifiers	Auth Model
`mortgagee`	`investor_id`, `loan_number`	Shared passphrase + mTLS cert
`agent`	`nmls_id`, `loan_number`	WebAuthn challenge
`policyholder`	`email`, `phone`, `date_of_birth`, `loan_number`	SMS OTP
`auditor`	`badge_id`, `nda_hash`	Badge + NDA validation, time-boxed

Example: Mortgagee (Pre-populated Identifiers)

Store the lender’s identifiers at registration. The policy engine matches these stored values at access time — no runtime submission needed.

Insurance
Real Estate
Healthcare
Financial Services

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"
    }
  }'

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": "Pacific West Mortgage",
    "email": "[email protected]",
    "stakeholderClass": "mortgagee",
    "identifiers": {
      "lender_id": "PWM-2200",
      "file_number": "FILE-2025-10042"
    }
  }'

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": "Anthem Blue Cross",
    "email": "[email protected]",
    "stakeholderClass": "mortgagee",
    "identifiers": {
      "payer_id": "ANTHEM-00112",
      "member_id": "MBR-2025-44210"
    }
  }'

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": "Vanguard Warehouse Lending",
    "email": "[email protected]",
    "stakeholderClass": "mortgagee",
    "identifiers": {
      "investor_id": "VWL-5500",
      "loan_number": "LN-2025-78300"
    }
  }'

Example: Policyholder (Runtime Submission)

Add a policyholder with just name and email. They’ll submit date_of_birth and policy_number when accessing the portal — the policy engine validates the submitted values against the recipe.

Insurance
Real Estate
Healthcare
Financial Services

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"
  }'

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": "Maria Espinoza",
    "email": "[email protected]",
    "stakeholderClass": "policyholder"
  }'

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": "Robert Kim",
    "email": "[email protected]",
    "stakeholderClass": "policyholder"
  }'

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": "Jennifer & Thomas Wright",
    "email": "[email protected]",
    "stakeholderClass": "policyholder"
  }'

Example: Policyholder (Pre-populated)

Alternatively, pre-populate all identifiers at registration. The phone is required for SMS OTP delivery, so storing it upfront is recommended even if other identifiers are submitted at runtime.

Insurance
Real Estate
Healthcare
Financial Services

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"
    }
  }'

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": "Maria Espinoza",
    "email": "[email protected]",
    "stakeholderClass": "policyholder",
    "identifiers": {
      "phone": "+1-213-555-0198",
      "date_of_birth": "1990-08-22",
      "file_number": "FILE-2025-10042"
    }
  }'

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": "Robert Kim",
    "email": "[email protected]",
    "stakeholderClass": "policyholder",
    "identifiers": {
      "phone": "+1-312-555-0234",
      "date_of_birth": "1975-11-03",
      "member_id": "MBR-2025-44210"
    }
  }'

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": "Jennifer & Thomas Wright",
    "email": "[email protected]",
    "stakeholderClass": "policyholder",
    "identifiers": {
      "phone": "+1-704-555-0312",
      "date_of_birth": "1988-03-27",
      "loan_number": "LN-2025-78300"
    }
  }'

Example: Auditor

Insurance
Real Estate
Healthcare
Financial Services

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..."
    }
  }'

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": "KPMG — Nathan Brooks",
    "email": "[email protected]",
    "stakeholderClass": "auditor",
    "identifiers": {
      "badge_id": "AUD-KPMG-2025-0119",
      "nda_hash": "sha256:b4f9a2c8d1e7f3a0..."
    }
  }'

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": "HHS OIG — Angela Foster",
    "email": "[email protected]",
    "stakeholderClass": "auditor",
    "identifiers": {
      "badge_id": "HHS-OIG-2025-0087",
      "nda_hash": "sha256:c7d2e9f1a3b5..."
    }
  }'

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": "OCC — Sandra Liu",
    "email": "[email protected]",
    "stakeholderClass": "auditor",
    "identifiers": {
      "badge_id": "OCC-2025-EX-0204",
      "nda_hash": "sha256:a1b2c3d4e5f6..."
    }
  }'

Response

{
  "id": "rcp_01HQ3N...",
  "dockId": "dock_01HQ3K...",
  "name": "First National Bank",
  "email": "[email protected]",
  "stakeholderClass": "mortgagee",
  "identifiers": {
    "lender_id": "LND-4821",
    "policy_number": "POL-2025-88401"
  },
  "createdAt": "2025-01-15T10:32:00.000Z"
}

Error Handling

Status	Condition
`400`	`email` is not a valid email format
`401`	Missing or invalid API key
`404`	Dock not found

Email addresses are normalized to lowercase and indexed per dock. A dock cannot have two recipients with the same email address. For auditors, compute the nda_hash by running sha256sum on the signed NDA PDF before registration.Identifiers are optional. You can create a recipient with just name and email, then let them submit identifiers at access time through the portal or API. The policy’s match.identifiers defines what’s required — identifiers can come from the stored record, runtime submission, or both. See Identifier Resolution for details.

API Reference

Docks

Artifacts

Recipients

Recipient Groups

Policies

Retrieval

Secrets

Audit

Notifications

Identity

Create a Recipient