Create a Retrieval Job

Creates a new bulk retrieval job. The job asynchronously prepares signed download URLs for matching artifacts based on the filters provided. Bulk retrieval is used by mortgagees (via API) and agents (via portal bulk download).

POST /v1/retrieval/jobs

Request Body

Parameter	Type	Required	Description
`dockId`	string	Required	The dock to retrieve artifacts from
`recipientId`	string	Required	The recipient requesting retrieval
`artifactIds`	array	Optional	Specific artifact IDs to retrieve
`metadata`	object	Optional	Filter artifacts by metadata key-value pairs
`sinceTimestamp`	string	Optional	Only include artifacts created after this ISO 8601 timestamp

Example: Mortgagee Daily Sync

Insurance
Real Estate
Healthcare
Financial Services

A mortgage lender pulls all new declaration pages since yesterday via API, authenticating with shared passphrase + mutual TLS:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "metadata": {
      "document_type": "declaration-page"
    },
    "sinceTimestamp": "2025-01-14T00:00:00.000Z"
  }'

A warehouse lender pulls all new closing disclosures since yesterday via API, authenticating with shared passphrase + mutual TLS:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "metadata": {
      "document_type": "closing-disclosure"
    },
    "sinceTimestamp": "2025-01-14T00:00:00.000Z"
  }'

A payer pulls all new explanation-of-benefits documents since yesterday via API, authenticating with shared passphrase + mutual TLS:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "metadata": {
      "document_type": "explanation-of-benefits"
    },
    "sinceTimestamp": "2025-01-14T00:00:00.000Z"
  }'

An investor pulls all new promissory notes since yesterday via API, authenticating with shared passphrase + mutual TLS:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "metadata": {
      "document_type": "promissory-note"
    },
    "sinceTimestamp": "2025-01-14T00:00:00.000Z"
  }'

Example: Agent Client Batch

Insurance
Real Estate
Healthcare
Financial Services

An agent pulls all documents for a specific client’s policy number:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3S...",
    "metadata": {
      "policy_number": "POL-2025-88401"
    }
  }'

A title agent pulls all documents for a specific file number:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3S...",
    "metadata": {
      "file_number": "FILE-2025-10042"
    }
  }'

A provider pulls all documents for a specific member ID:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3S...",
    "metadata": {
      "member_id": "MBR-2025-44210"
    }
  }'

A loan officer pulls all documents for a specific loan number:

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3S...",
    "metadata": {
      "loan_number": "LN-2025-78300"
    }
  }'

Example: Targeted Pull by Artifact IDs

Retrieve specific artifacts by ID (useful for retry or selective download):

curl -X POST https://api.docyard.io/v1/retrieval/jobs \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "recipientId": "rcp_01HQ3N...",
    "artifactIds": ["art_01HQ3M...", "art_01HQ3N..."]
  }'

Response

{
  "id": "job_01HQ3Q...",
  "dockId": "dock_01HQ3K...",
  "status": "PENDING",
  "totalCount": 0,
  "readyCount": 0,
  "errorCount": 0,
  "createdAt": "2025-01-15T10:34:00.000Z"
}

Filtering Options

Filter	Description	Common Use
`artifactIds`	Retrieve specific artifacts by ID	Targeted pulls, retry
`sinceTimestamp`	Only artifacts uploaded after this date	Daily incremental sync
`metadata`	Filter by artifact metadata key-value pairs	By doc type, state, LOB

Error Handling

Status	Condition
`400`	`dockId` is missing
`400`	`sinceTimestamp` is not a valid ISO 8601 date
`401`	Missing or invalid API key
`404`	Dock or recipient not found

Retrieval jobs are processed asynchronously. After creation, poll the Retrieve Job endpoint to check the status. Once the status is COMPLETED, use Job Results to get signed download URLs. Signed URLs expire after 1 hour and result sets expire after 24 hours.

Who Uses Bulk Retrieval?

Persona	Usage	Auth
Mortgagee	Daily incremental sync via API	Shared passphrase + mTLS
Agent	Client batch download via portal or API	WebAuthn challenge
Policyholder	Does not use bulk retrieval — single document via portal	SMS OTP
Auditor	Does not use bulk retrieval — read-only portal, no downloads	Badge ID + NDA hash

API Reference

Docks

Artifacts

Recipients

Recipient Groups

Policies

Retrieval

Secrets

Audit

Notifications

Identity

Create a Retrieval Job