Create Organization
Creates a new organization — the top-level tenant entity that owns docks, parties, and machine clients.
Request Body
| Parameter | Type | Required | Description |
|---|
name | string | Required | Display name for the organization |
metadata | object | Optional | Custom JSON attributes (e.g., {"industry": "financial-services"}) |
Example Request
Financial Services
Healthcare
Real Estate
curl -X POST https://api.docyard.io/v1/organizations \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"name": "Bank of America",
"metadata": {
"industry": "financial-services",
"region": "north-america",
"tier": "enterprise"
}
}'
curl -X POST https://api.docyard.io/v1/organizations \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"name": "Metro Health System",
"metadata": {
"industry": "healthcare",
"facilities": 12,
"region": "metro-chicago"
}
}'
curl -X POST https://api.docyard.io/v1/organizations \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"name": "Premier Title Services",
"metadata": {
"industry": "real-estate",
"branches": 8,
"states": ["CA", "NV", "AZ"]
}
}'
Response
{
"id": "org_01HQ3K9B2...",
"name": "Bank of America",
"slug": "bank-of-america",
"metadata": {
"industry": "financial-services",
"region": "north-america",
"tier": "enterprise"
},
"createdAt": "2024-03-01T12:00:00.000Z",
"updatedAt": "2024-03-01T12:00:00.000Z",
"_count": {
"docks": 0,
"parties": 0,
"machineClients": 0
}
}
Response Fields
| Field | Type | Description |
|---|
id | string | Unique organization identifier (prefix: org_) |
name | string | Organization display name |
slug | string | URL-friendly unique identifier (auto-generated from name) |
metadata | object | Custom JSON attributes |
createdAt | string | ISO 8601 timestamp |
updatedAt | string | ISO 8601 timestamp |
_count | object | Resource counts (docks, parties, machine clients) |
Error Handling
| Status | Condition |
|---|
400 | Invalid request body |
401 | Missing or invalid API key |
409 | Organization name or slug already exists |
The slug is automatically generated from the organization name. If “Bank of America” already exists, the next one might be “bank-of-america-1”.
Next Steps
After creating an organization:
- Create a dock under this organization
- Create parties for real-world actors
- Create machine clients for automated integrations
