> ## Documentation Index > Fetch the complete documentation index at: https://docs.docyard.cc/llms.txt > Use this file to discover all available pages before exploring further. # Collectors > Entities that retrieve artifacts from the lake # 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: | Type | Example | | -------------------- | ----------------------------------------- | | **Mortgage Lenders** | Retrieve insurance declarations for loans | | **Title Companies** | Get closing documents | | **Banks** | Access loan agreements, escrow docs | | **Auditors** | Review compliance documents | | **Individuals** | Get their own policy documents | ## Collector Onboarding Collector onboarding involves verification because they access sensitive documents. ### Step 1: Sign Up Provide basic information: ```json theme={null} { "organization_name": "FirstCity Bank", "business_email": "operations@firstcitybank.com", "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} POST /api/v1/docks { "name": "Production Dock", "description": "Main retrieval endpoint" } ``` ### Step 7: Receive Credentials Get API keys for authentication: ```json theme={null} { "dock_id": "dock-xyz789", "api_key": "dk_live_collector_aaaaaaaa", "api_secret": "dk_secret_collector_bbbbbbbb" } ``` ## Collector Workflow
👆 Click to expand: Collector Document Consumption Journey ```mermaid theme={null} sequenceDiagram participant C as Collector participant API as Docyard API participant L as The Lake participant D as Distributor Note over C,L: COLLECTOR DOCUMENT CONSUMPTION JOURNEY C->>API: 1. Discover available lock types API-->>C: List of lock types in the lake C->>API: 2. Search for artifacts C->>API: POST /dock/search Note right of C: - filters (document_type, lock values)
- pagination API-->>C: List of matching artifacts C->>API: 3. Present keys & retrieve C->>API: POST /dock/retrieve/{id} Note right of C: - keys (lock values they have)
- e.g., policy_number: "POL-123" API->>L: Calculate score L->>API: Check threshold alt Score >= Threshold API-->>C: Access granted! Note right of C: Artifact content returned else Score < Threshold API-->>C: Access denied Note right of C: "Score too low. Provide more keys." end loop Nightly Sync C->>API: Search for new artifacts C->>API: Batch retrieve with keys API-->>C: Download available documents end ```
### 1. Discover Available Lock Types See what metadata fields exist in the lake: ```json theme={null} GET /api/v1/dock/lock-types ``` ```json theme={null} { "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: ```json theme={null} 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: ```json theme={null} POST /api/v1/dock/retrieve/art-abc123 { "keys": { "policy_number": "POL-12345678" } } ``` ### 4. Get Results **If access granted:** ```json theme={null} { "status": "granted", "score": 20, "threshold": 20, "content": "", "content_type": "application/pdf", "metadata": { "policy_number": "POL-12345678", "effective_date": "2026-03-15" } } ``` **If access denied:** ```json theme={null} { "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 Type | Permission | Notes | | ---------------- | ------------- | ------------------------------------ | | `policy_number` | ✅ Allowed | Declared and verified | | `loan_number` | ✅ Allowed | Declared and verified | | `mortgagee_name` | ⚠️ Restricted | Can search but not use for retrieval | | `tax_id` | ❌ Not Allowed | Not declared | ### Attempting Unauthorized Access ```json theme={null} POST /api/v1/dock/retrieve/art-abc123 { "keys": { "tax_id": "12-3456789" } } ``` ```json theme={null} { "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: ```json theme={null} { "filters": { "document_type": "declaration_page" } } ``` ### Filter by Lock Values Find specific policies: ```json theme={null} { "filters": { "policy_number": "POL-123" } } ``` ### Filter by Date Find recently uploaded artifacts: ```json theme={null} { "filters": { "created_after": "2026-03-01", "created_before": "2026-03-31" } } ``` ### Combine Filters ```json theme={null} { "filters": { "document_type": "declaration_page", "mortgagee_name": "FirstCity Bank", "effective_date_after": "2026-01-01" } } ``` ## Bulk Retrieval For large document sets: ```json theme={null} POST /api/v1/dock/retrieve/batch { "artifact_ids": ["art-001", "art-002", "art-003"], "keys": { "policy_number": "POL-123" } } ``` ```json theme={null} { "results": [ { "artifact_id": "art-001", "status": "granted", "content": "" }, { "artifact_id": "art-002", "status": "granted", "content": "" }, { "artifact_id": "art-003", "status": "denied", "score": 5, "threshold": 20 } ] } ``` ## Authentication Collectors authenticate using API keys: ```bash theme={null} 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 | Action | Limit | | ----------------- | ----------------- | | Search | 300/minute | | Retrieve (single) | 100/minute | | Retrieve (batch) | 20 batches/minute | | List lock types | 100/minute | ## Audit Trail All collector actions are logged: ```json theme={null} { "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: ```json theme={null} 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 * Understand \[Docks]\(/concepts/upload endpoints-and-docks) * Learn about [Lock-Key-Weight](/concepts/lock-key-weight) * See the [API Reference](/api-reference/docks)