Skip to main content

​
Assign Party Role

Assigns a role to a party within a specific dock, enabling the party to participate in document workflows as either a distributor or recipient. 
POST /v1/organizations/:orgId/parties/:partyId/roles

​
Path Parameters

ParameterTypeRequiredDescription
orgIdstringRequiredOrganization ID (prefix: org_)
partyIdstringRequiredParty ID (prefix: pty_)

​
Request Body

ParameterTypeRequiredDescription
dockIdstringRequiredDock ID where the role is assigned
rolestringRequiredRole type: DISTRIBUTOR or RECIPIENT

​
Example Request

curl -X POST https://api.docyard.io/v1/organizations/org_01HQ3K.../parties/pty_01HQ3L.../roles \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "dockId": "dock_01HQ3M...",
    "role": "DISTRIBUTOR"
  }'

​
Response

{
  "id": "dpr_01HQ3K9B2...",
  "dockId": "dock_01HQ3M...",
  "partyId": "pty_01HQ3L...",
  "role": "DISTRIBUTOR",
  "createdAt": "2024-03-01T12:00:00.000Z"
}

​
Response Fields

FieldTypeDescription
idstringDockPartyRole identifier (prefix: dpr_)
dockIdstringDock where role is assigned
partyIdstringParty receiving the role
rolestringDISTRIBUTOR or RECIPIENT
createdAtstringISO 8601 timestamp

​
Validation

The endpoint validates that:
  • The party belongs to the specified organization
  • The dock belongs to the same organization
  • The role combination (dockId + partyId + role) is unique

​
Error Handling

StatusCondition
400Invalid role type or missing required fields
401Missing or invalid API key
403Party or dock doesn’t belong to organization
404Organization, party, or dock not found
409Role already assigned (duplicate)

​
Multi-Role Pattern

A party can have different roles in different docks: 
Party: First American Title
├── Dock 1 (Underwriting): Role = DISTRIBUTOR
├── Dock 2 (Closing): Role = DISTRIBUTOR
└── Dock 3 (Agent Portal): Role = RECIPIENT
This enables the same entity to participate in multiple capacities across your organization.

​
Auto-Assignment

When creating a recipient with a partyId, if the party doesn’t have the RECIPIENT role in that dock, it’s automatically assigned.

​
Next Steps

After assigning a role:
  • Party can now participate in the dock according to their role
  • Create recipients linked to this party
  • Create machine clients scoped to this dock