Parties

A party represents a real-world actor — either an individual or an organization — that participates in document distribution workflows. Parties enable identity reuse across docks, allowing the same entity to act as a distributor in one dock and a recipient in another.

Core Concept

Think of parties as your counterparty directory. Instead of creating separate recipient records for the same entity in every dock, you create one party record and assign them roles where needed.

Party vs. Recipient

Aspect	Party	Recipient
Scope	Organization-level	Dock-level
Represents	Real-world entity	Access grant within a specific dock
Reusability	One party, multiple docks	Tied to a single dock
Identity	Persistent, consistent	Context-specific
Linkage	Can be linked to recipients	Can link to a party

Example: “First American Title” is a party (the company). Within Dock A, they’re a linked recipient who receives mortgage documents. Within Dock B, they’re a linked distributor who sends title insurance policies.

Party Types

Individual

Natural persons who participate in workflows:

Homeowners receiving closing documents
Patients receiving medical records
Investors receiving financial statements
Auditors reviewing compliance documents

Organization

Legal entities that participate in workflows:

Title companies
Insurance carriers
Lenders and banks
Healthcare providers
Government agencies
Escrow companies

Party Roles

Roles define what a party can do within a specific dock:

DISTRIBUTOR

The party uploads artifacts, creates policies, and manages distribution:

Permissions: Create artifacts, define policies, add recipients
Typical Actors: Title companies, insurance carriers, healthcare providers
Example: A title company distributing closing packets to lenders and buyers

RECIPIENT

The party retrieves artifacts through access recipes:

Permissions: Access documents via policies, download via retrieval API
Typical Actors: Lenders, insurers, auditors, regulators, patients
Example: A lender receiving loan documentation from a title company

Multi-Role Parties

A party can hold different roles in different docks:

Party: ABC Title Company
├── Dock 1: Underwriting Division
│   └── Role: DISTRIBUTOR (sending title policies to insurers)
├── Dock 2: Closing Division
│   └── Role: DISTRIBUTOR (sending closing packets to lenders/buyers)
└── Dock 3: Agent Network
    └── Role: RECIPIENT (receiving rate sheets from insurers)

This is a powerful pattern for entities that participate in document ecosystems in multiple capacities.

Real-World Scenarios

Title Company (Organization Party)

Party: Premier Title Services (type: ORGANIZATION) Scenario 1: Title Insurance Distribution

Dock: Insurance Partnerships
├── Party: Premier Title Services (Role: DISTRIBUTOR)
│   └── Action: Uploads title insurance policies
├── Party: First American Title Insurance (Role: RECIPIENT)
└── Party: Fidelity National Title (Role: RECIPIENT)

Scenario 2: Closing Document Distribution

Dock: Residential Closings
├── Party: Premier Title Services (Role: DISTRIBUTOR)
│   └── Action: Uploads closing disclosure packages
├── Party: Wells Fargo Mortgage (Role: RECIPIENT)
├── Party: John & Jane Homeowner (Role: RECIPIENT)
└── Party: Local City Government (Role: RECIPIENT)

Scenario 3: Rate Sheet Reception

Dock: Underwriter Communications
├── Party: First American Title Insurance (Role: DISTRIBUTOR)
│   └── Action: Uploads premium rate sheets
└── Party: Premier Title Services (Role: RECIPIENT)
    └── Action: Downloads rate sheets for calculations

Benefit: Premier Title maintains consistent identity (tax ID, registration) across all three scenarios.

Patient (Individual Party)

Party: Sarah Johnson (type: INDIVIDUAL) Scenario 1: Hospital Records

Dock: Metro General Hospital
├── Party: Medical Records Dept (Role: DISTRIBUTOR)
│   └── Action: Uploads discharge summaries
└── Party: Sarah Johnson (Role: RECIPIENT)
    └── Action: Retrieves her medical records

Scenario 2: Insurance Claims

Dock: Insurance Claims Processing
├── Party: Metro General Hospital (Role: DISTRIBUTOR)
│   └── Action: Uploads billing records
└── Party: Sarah Johnson (Role: RECIPIENT)
    └── Action: Receives claim documentation

Scenario 3: Specialist Referral

Dock: Cardiology Associates
├── Party: Dr. Smith's Office (Role: DISTRIBUTOR)
│   └── Action: Uploads referral notes
└── Party: Sarah Johnson (Role: RECIPIENT)
    └── Action: Accesses specialist recommendations

Benefit: Sarah’s identity (name, DOB, medical record number) is consistent across all healthcare interactions.

Lender (Organization Party)

Party: Wells Fargo Mortgage (type: ORGANIZATION) Scenario 1: Loan Origination

Dock: Purchase Loans
├── Party: Wells Fargo Mortgage (Role: DISTRIBUTOR)
│   └── Action: Uploads loan commitment letters
└── Party: Various Title Companies (Role: RECIPIENT)

Scenario 2: Servicing Transfer

Dock: Loan Servicing
├── Party: Wells Fargo Mortgage (Role: RECIPIENT)
│   └── Action: Receives servicing transfer packages
└── Party: Various Originators (Role: DISTRIBUTOR)

Scenario 3: Investor Reporting

Dock: Investor Relations
├── Party: Wells Fargo Mortgage (Role: DISTRIBUTOR)
│   └── Action: Uploads monthly loan performance reports
└── Party: Fannie Mae (Role: RECIPIENT)

Benefit: Wells Fargo’s identity is authoritative whether they’re originating, servicing, or reporting.

Party Lifecycle

1. Create Party

Create the party record at the organization level:

curl -X POST https://api.docyard.io/v1/organizations/{orgId}/parties \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ORGANIZATION",
    "name": "First American Title Insurance",
    "email": "[email protected]",
    "externalRef": "FEIN:94-1234567",
    "metadata": {
      "industry": "title-insurance",
      "region": "nationwide",
      "primaryContact": "Jane Smith"
    }
  }'

Response:

{
  "id": "pty_01HQ3K...",
  "organizationId": "org_01HQ3K...",
  "type": "ORGANIZATION",
  "name": "First American Title Insurance",
  "email": "[email protected]",
  "externalRef": "FEIN:94-1234567",
  "metadata": {
    "industry": "title-insurance",
    "region": "nationwide",
    "primaryContact": "Jane Smith"
  },
  "createdAt": "2024-03-01T12:00:00Z",
  "updatedAt": "2024-03-01T12:00:00Z"
}

2. Assign Role in Dock

Grant the party a role within a specific dock:

curl -X POST https://api.docyard.io/v1/organizations/{orgId}/parties/{partyId}/roles \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3K...",
    "role": "RECIPIENT"
  }'

Validation:

Party must belong to the organization
Dock must belong to the same organization
Role combination (dockId + partyId + role) must be unique

3. Link to Recipient (Optional)

When creating a recipient, link them to the party:

curl -X POST https://api.docyard.io/v1/docks/{dockId}/recipients \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First American Title Insurance",
    "email": "[email protected]",
    "partyId": "pty_01HQ3K...",
    "identifiers": {
      "taxId": "94-1234567"
    }
  }'

If the party doesn’t have the RECIPIENT role in this dock, the system will automatically assign it.

4. Query Party Roles

List all roles a party has across docks:

curl https://api.docyard.io/v1/organizations/{orgId}/parties/{partyId}/roles \
  -H "Authorization: Bearer dk_live_..."

Response:

{
  "data": [
    {
      "id": "dpr_01HQ3K...",
      "dockId": "dock_01HQ3L...",
      "dockName": "Underwriting Division",
      "role": "DISTRIBUTOR",
      "createdAt": "2024-03-01T12:00:00Z"
    },
    {
      "id": "dpr_01HQ3M...",
      "dockId": "dock_01HQ3N...",
      "dockName": "Agent Portal",
      "role": "RECIPIENT",
      "createdAt": "2024-03-01T12:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "pageSize": 20
  }
}

Party Identifiers

Parties can have various identifiers for different contexts:

External Reference

Use the externalRef field to store authoritative identifiers:

Organizations: Federal EIN, DUNS number, state business registration
Individuals: Social Security Number (hashed), patient ID, employee ID

{
  "externalRef": "EIN:94-1234567",
  "metadata": {
    "duns": "123456789",
    "nmlsId": "12345"
  }
}

Recipient Identifiers

When a party is linked to a recipient, they inherit the dock’s identifier schema:

Insurance: NAIC number, FEIN
Healthcare: NPI number, medical record number
Real Estate: License number, escrow agent ID

Best Practices

Creating Parties

✅ Do:

Create one party per real-world entity
Use consistent externalRef for authoritative identification
Include industry and region in metadata for filtering
Set a primary email for communications

❌ Don’t:

Create duplicate parties for the same entity
Put sensitive PII in metadata (use externalRef for SSNs, hashed)
Create parties at the dock level (use organization scope)

Assigning Roles

✅ Do:

Assign DISTRIBUTOR role to entities that upload documents
Assign RECIPIENT role to entities that retrieve documents
Review role assignments quarterly
Use descriptive dock names for clarity

❌ Don’t:

Assign both roles in the same dock (creates confusion)
Forget to link recipients to parties (loses identity benefits)
Grant DISTRIBUTOR role to external parties without verification

Industry Patterns

Financial Services:

Create parties for: lenders, title companies, insurers, auditors
Common external refs: FEIN, NMLS ID, DUNS
Typical metadata: credit ratings, geographic regions, relationship tiers

Healthcare:

Create parties for: providers, insurers, patients, government agencies
Common external refs: NPI, tax ID, medical record number
Typical metadata: specialties, network status, compliance certifications

Real Estate:

Create parties for: agents, brokers, lenders, title companies, buyers, sellers
Common external refs: license numbers, MLS IDs
Typical metadata: market areas, transaction volume, specialization

Security Considerations

Data Isolation

Party data is organization-scoped
Party roles are dock-scoped (but validated against organization)
Party identifiers are visible only within the organization
Cross-organization party matching is not supported (by design)

Privacy

Store sensitive identifiers (SSN, MRN) in externalRef, not metadata
Consider hashing sensitive identifiers
Party email addresses are used for notifications (ensure opt-in)

Organizations — Top-level tenant boundary
Docks — Workspaces where parties have roles
Recipients — Access grants linked to parties
Machine Authentication — Automated access by parties

Get Started

Core Concepts

Parties

Parties

Core Concept

Party vs. Recipient

Party Types

Individual

Organization

Party Roles

DISTRIBUTOR

RECIPIENT

Multi-Role Parties

Real-World Scenarios

Title Company (Organization Party)

Patient (Individual Party)

Lender (Organization Party)

Party Lifecycle

1. Create Party

2. Assign Role in Dock

3. Link to Recipient (Optional)

4. Query Party Roles

Party Identifiers

External Reference

Recipient Identifiers

Best Practices

Creating Parties

Assigning Roles

Industry Patterns

Security Considerations

Data Isolation

Privacy

API Endpoints

Get Started

Core Concepts

​Parties

​Core Concept

​Party vs. Recipient

​Party Types

​Individual

​Organization

​Party Roles

​DISTRIBUTOR

​RECIPIENT

​Multi-Role Parties

​Real-World Scenarios

​Title Company (Organization Party)

​Patient (Individual Party)

​Lender (Organization Party)

​Party Lifecycle

​1. Create Party

​2. Assign Role in Dock

​3. Link to Recipient (Optional)

​4. Query Party Roles

​Party Identifiers

​External Reference

​Recipient Identifiers

​Best Practices

​Creating Parties

​Assigning Roles

​Industry Patterns

​Security Considerations

​Data Isolation

​Privacy

​Related Concepts

​API Endpoints

Parties

Core Concept

Party vs. Recipient

Party Types

Individual

Organization

Party Roles

DISTRIBUTOR

RECIPIENT

Multi-Role Parties

Real-World Scenarios

Title Company (Organization Party)

Patient (Individual Party)

Lender (Organization Party)

Party Lifecycle

1. Create Party

2. Assign Role in Dock

3. Link to Recipient (Optional)

4. Query Party Roles

Party Identifiers

External Reference

Recipient Identifiers

Best Practices

Creating Parties

Assigning Roles

Industry Patterns

Security Considerations

Data Isolation

Privacy

Related Concepts

API Endpoints