Skip to main content

​
Collectors

Collectors are entities that retrieve artifacts from the lake. They use docks to fish artifacts.

​
Who Can Be a Collector?

Anyone who needs to receive documents through Docyard:
TypeExample
Mortgage LendersRetrieve insurance declarations for loans
Title CompaniesGet closing documents
BanksAccess loan agreements, escrow docs
AuditorsReview compliance documents
IndividualsGet their own policy documents

​
Collector Onboarding

Collector onboarding involves verification because they access sensitive documents.

​
Step 1: Sign Up

Provide basic information: 
{
  "organization_name": "FirstCity Bank",
  "business_email": "[email protected]",
  "industry": "mortgage_lending",
  "website": "https://firstcitybank.com"
}

​
Step 2: Business Verification (KYC)

Submit verification documents:
  • Business license
  • Tax ID / EIN
  • Proof of business address
  • Industry credentials (NMLS ID for mortgage lenders, etc.)

​
Step 3: Key Declaration

Declare which lock types you have access to: 
{
  "declared_locks": [
    "policy_number",
    "loan_number",
    "mortgagee_name",
    "effective_date"
  ],
  "declaration_notes": "We receive policy numbers directly from insurance carriers via nightly feeds"
}

​
Step 4: Intent Declaration

Specify what you intend to collect: 
{
  "intended_artifacts": [
    "Insurance Declaration Pages",
    "Loan Agreements",
    "Closing Documents"
  ],
  "use_case": "Mortgage lending due diligence and loan servicing"
}

​
Step 5: Manual Review

Docyard admins review your application:
  • Verify business legitimacy
  • Validate declared locks make sense
  • Assess appropriateness of intended use

​
Step 6: Approval & Dock Setup

Once approved: 
POST /api/v1/docks
{
  "name": "Production Dock",
  "description": "Main retrieval endpoint"
}

​
Step 7: Receive Credentials

Get API keys for authentication: 
{
  "dock_id": "dock-xyz789",
  "api_key": "dk_live_collector_aaaaaaaa",
  "api_secret": "dk_secret_collector_bbbbbbbb"
}

​
Collector Workflow

​
1. Discover Available Lock Types

See what metadata fields exist in the lake: 
GET /api/v1/dock/lock-types

{
  "lock_types": [
    { "name": "policy_number", "usage_count": 15420 },
    { "name": "loan_number", "usage_count": 8932 },
    { "name": "mortgagee_name", "usage_count": 7231 },
    { "name": "effective_date", "usage_count": 12453 }
  ]
}

​
2. Search for Artifacts

Find artifacts matching your keys: 
POST /api/v1/dock/search
{
  "filters": {
    "document_type": "declaration_page",
    "mortgagee_name": "FirstCity Bank"
  },
  "pagination": {
    "page": 1,
    "limit": 50
  }
}

​
3. Present Keys & Retrieve

When you find artifacts you want: 
POST /api/v1/dock/retrieve/art-abc123
{
  "keys": {
    "policy_number": "POL-12345678"
  }
}

​
4. Get Results

If access granted: 
{
  "status": "granted",
  "score": 20,
  "threshold": 20,
  "content": "<pdf-data>",
  "content_type": "application/pdf",
  "metadata": {
    "policy_number": "POL-12345678",
    "effective_date": "2026-03-15"
  }
}
If access denied: 
{
  "status": "denied",
  "score": 5,
  "threshold": 20,
  "message": "Score (5) below threshold (20). Provide additional keys."
}

​
Key Permissions

After KYC approval, collectors are configured with lock type permissions - which lock types they’re allowed to use.

​
Permission Model

Lock TypePermissionNotes
policy_number✅ AllowedDeclared and verified
loan_number✅ AllowedDeclared and verified
mortgagee_name⚠️ RestrictedCan search but not use for retrieval
tax_id❌ Not AllowedNot declared

​
Attempting Unauthorized Access

POST /api/v1/dock/retrieve/art-abc123
{
  "keys": {
    "tax_id": "12-3456789"
  }
}

{
  "status": "denied",
  "reason": "unauthorized_lock_type",
  "message": "You are not authorized to use the 'tax_id' lock type."
}

​
Search & Discovery

​
Filter by Document Type

Find all insurance declarations: 
{
  "filters": {
    "document_type": "declaration_page"
  }
}

​
Filter by Lock Values

Find specific policies: 
{
  "filters": {
    "policy_number": "POL-123"
  }
}

​
Filter by Date

Find recently uploaded artifacts: 
{
  "filters": {
    "created_after": "2026-03-01",
    "created_before": "2026-03-31"
  }
}

​
Combine Filters

{
  "filters": {
    "document_type": "declaration_page",
    "mortgagee_name": "FirstCity Bank",
    "effective_date_after": "2026-01-01"
  }
}

​
Bulk Retrieval

For large document sets: 
POST /api/v1/dock/retrieve/batch
{
  "artifact_ids": ["art-001", "art-002", "art-003"],
  "keys": {
    "policy_number": "POL-123"
  }
}

{
  "results": [
    {
      "artifact_id": "art-001",
      "status": "granted",
      "content": "<file-data>"
    },
    {
      "artifact_id": "art-002",
      "status": "granted",
      "content": "<file-data>"
    },
    {
      "artifact_id": "art-003",
      "status": "denied",
      "score": 5,
      "threshold": 20
    }
  ]
}

​
Authentication

Collectors authenticate using API keys: 
curl -X POST https://api.docyard.io/v1/dock/search \
  -H "X-API-Key: dk_live_collector_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_collector_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

​
Rate Limits

ActionLimit
Search300/minute
Retrieve (single)100/minute
Retrieve (batch)20 batches/minute
List lock types100/minute

​
Audit Trail

All collector actions are logged: 
{
  "event": "artifact_retrieved",
  "dock_id": "dock-xyz789",
  "collector_id": "coll-abc123",
  "artifact_id": "art-123abc",
  "keys_used": ["policy_number"],
  "score": 20,
  "threshold": 20,
  "result": "granted",
  "timestamp": "2026-03-15T14:30:00Z"
}

​
Requesting Additional Permissions

If you need access to additional lock types: 
POST /api/v1/docks/dock-xyz789/request-permissions
{
  "requested_locks": ["vin_number", "vehicle_make"],
  "justification": "We now also handle auto insurance verification"
}
Docyard admins will review and approve/reject.

​
Next Steps