Skip to main content

​
Import Recipients (CSV)

Uploads a CSV file to create recipients in bulk. The CSV is parsed row-by-row with per-row error reporting. Use this for large catalogs with mixed persona types. 
POST /v1/docks/:dockId/recipients/import/csv

​
Path Parameters

ParameterTypeDescription
dockIdstringThe dock ID

​
Request Body

Multipart form data with a CSV file.
FieldTypeRequiredDescription
filefileRequiredCSV file with recipient data

​
CSV Format

Required columns: name, email Optional columns by persona:
ColumnMaps ToUsed By
stakeholder_classstakeholderClassAll personas
lender_ididentifiers.lender_idMortgagee
policy_numberidentifiers.policy_numberMortgagee, Agent, Policyholder
agency_codeidentifiers.agency_codeAgent
phoneidentifiers.phonePolicyholder
date_of_birthidentifiers.date_of_birthPolicyholder
badge_ididentifiers.badge_idAuditor
nda_hashidentifiers.nda_hashAuditor

​
Example CSV

name,email,stakeholder_class,lender_id,agency_code,phone,date_of_birth,policy_number,badge_id,nda_hash
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,1983-06-15,POL-2025-88401,,
Deloitte — Maria Gonzalez,[email protected],auditor,,,,,,AUD-DT-2025-0042,sha256:e3b0c44298fc1c149afbf4c8996fb924...

​
Example Request

curl -X POST https://api.docyard.io/v1/docks/dock_01HQ3K.../recipients/import/csv \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -F "[email protected]"

​
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", "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" }
  ]
}

​
Error Handling

StatusCondition
400No file provided or file is not valid CSV
400CSV exceeds maximum row count (10,000 rows)
401Missing or invalid API key
404Dock not found
Rows with missing name or email columns are skipped and reported in the errors array. Empty identifier columns are ignored (not stored as empty strings). Email addresses are normalized to lowercase — duplicate emails within the same dock are rejected per-row.