Skip to main content

​
Create Party

Creates a new party — a real-world actor (individual or organization) that can participate in document workflows across multiple docks. 
POST /v1/organizations/:orgId/parties

​
Path Parameters

ParameterTypeRequiredDescription
orgIdstringRequiredOrganization ID (prefix: org_)

​
Request Body

ParameterTypeRequiredDescription
typestringRequiredParty type: INDIVIDUAL or ORGANIZATION
namestringRequiredFull name (individual) or company name (organization)
emailstringOptionalPrimary contact email
externalRefstringOptionalExternal identifier (e.g., EIN:94-1234567, NPI:1234567890)
metadataobjectOptionalCustom JSON attributes

​
Example Request

curl -X POST https://api.docyard.io/v1/organizations/org_01HQ3K.../parties \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ORGANIZATION",
    "name": "First American Title Insurance",
    "email": "[email protected]",
    "externalRef": "EIN:94-1234567",
    "metadata": {
      "naic": "12345",
      "duns": "123456789",
      "primaryContact": "Jane Smith",
      "region": "nationwide"
    }
  }'

​
Response

{
  "id": "pty_01HQ3K9B2...",
  "organizationId": "org_01HQ3K9...",
  "type": "ORGANIZATION",
  "name": "First American Title Insurance",
  "email": "[email protected]",
  "externalRef": "EIN:94-1234567",
  "metadata": {
    "naic": "12345",
    "duns": "123456789",
    "primaryContact": "Jane Smith",
    "region": "nationwide"
  },
  "createdAt": "2024-03-01T12:00:00.000Z",
  "updatedAt": "2024-03-01T12:00:00.000Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique party identifier (prefix: pty_)
organizationIdstringParent organization ID
typestringINDIVIDUAL or ORGANIZATION
namestringParty display name
emailstringPrimary contact email
externalRefstringExternal identifier for integrations
metadataobjectCustom JSON attributes
createdAtstringISO 8601 timestamp
updatedAtstringISO 8601 timestamp

​
Error Handling

StatusCondition
400Invalid party type or missing required fields
401Missing or invalid API key
404Organization not found

​
Best Practices

External References: Use externalRef for authoritative identifiers:
  • Organizations: EIN, DUNS, state registration numbers
  • Individuals: NPI (healthcare), license numbers, hashed SSN
Metadata: Include context useful for filtering and integrations:
  • Industry classifications
  • Geographic regions
  • Relationship tiers
  • Specializations

​
Next Steps

After creating a party:
  1. Assign a role in a specific dock
  2. Create a recipient linked to this party
  3. Create a machine client associated with this party