Skip to main content

​
Batch Create Recipients

Creates multiple recipients in a single API call. Each item is processed independently — failures on individual items do not block others. Use this for onboarding mixed persona types together. 
POST /v1/docks/:dockId/recipients/batch

​
Path Parameters

ParameterTypeDescription
dockIdstringThe dock ID

​
Request Body

ParameterTypeRequiredDescription
recipientsarrayRequiredArray of recipient objects
recipients[].namestringRequiredRecipient display name
recipients[].emailstringRequiredRecipient email (stored lowercase)
recipients[].stakeholderClassstringOptionalPersona type: mortgagee, agent, policyholder, auditor
recipients[].identifiersobjectOptionalPersona-specific key-value identifiers

​
Example: Mixed Persona Batch

Onboard all four stakeholder 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"
        }
      },
      {
        "name": "Deloitte — Maria Gonzalez",
        "email": "[email protected]",
        "stakeholderClass": "auditor",
        "identifiers": {
          "badge_id": "AUD-DT-2025-0042",
          "nda_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb924..."
        }
      }
    ]
  }'

​
Response

{
  "success": 5,
  "failed": 0,
  "errors": [],
  "recipients": [
    {
      "id": "rcp_01HQ3N...",
      "name": "First National Bank",
      "email": "[email protected]",
      "stakeholderClass": "mortgagee"
    },
    {
      "id": "rcp_01HQ3P...",
      "name": "Citywide Credit Union",
      "email": "[email protected]",
      "stakeholderClass": "mortgagee"
    },
    {
      "id": "rcp_01HQ3Q...",
      "name": "Sarah Chen — Apex Insurance Group",
      "email": "[email protected]",
      "stakeholderClass": "agent"
    },
    {
      "id": "rcp_01HQ3R...",
      "name": "James Whitfield",
      "email": "[email protected]",
      "stakeholderClass": "policyholder"
    },
    {
      "id": "rcp_01HQ3S...",
      "name": "Deloitte — Maria Gonzalez",
      "email": "[email protected]",
      "stakeholderClass": "auditor"
    }
  ]
}

​
Partial Failure Example

If one item has an invalid email, the rest still succeed: 
{
  "success": 4,
  "failed": 1,
  "errors": [
    {
      "row": 2,
      "error": "email must be a valid email address",
      "name": "Invalid Recipient"
    }
  ],
  "recipients": [ ... ]
}

​
Error Handling

StatusCondition
400recipients array is empty
401Missing or invalid API key
404Dock not found
Per-item errors are returned in the errors array with their 0-based index. The overall request succeeds even if some items fail. Email addresses are normalized to lowercase — a dock cannot have two recipients with the same email. For auditors, compute the nda_hash by running sha256sum on the signed NDA PDF before registration.