Assignments
Assign a talent to an agency client.
Base URL https://api.klockwork.org. Send X-Klockwork-Key or Authorization: Bearer kw_…. An agency key acts as the agency that created it. JSON bodies use these fields. A missing required field returns 400 with { "error": "Validation failed", "details": {} }.
List assignments
GET /api/public/agency/assignments
Query:
| Field | Type | Required |
|---|---|---|
clientId | string (uuid) | no |
talentId | string (uuid) | no |
status | "active" or "pending" or "ended" or "open" or "all" | no |
Response 200: { assignments: Assignment[] }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
clerkOrgId | string, min 1 | yes |
talentId | string (uuid) | yes |
clientId | string (uuid) | yes |
status | "active" or "pending" or "ended" | yes |
talentDisplayName | string, min 1 or null | no |
clientDisplayName | string, min 1 or null | no |
createdAt | string | yes |
updatedAt | string | yes |
Create an assignment
POST /api/public/agency/assignments
Send an existing talent id, or a nested talent object that creates the talent and the assignment together. Assigning the same talent twice returns 400 { "error": "This talent is already assigned to this client" }.
Request body:
One of these bodies. Shape 1:
| Field | Type | Required |
|---|---|---|
clientId | string (uuid) | yes |
talentId | string (uuid) | yes |
One of these bodies. Shape 2:
| Field | Type | Required |
|---|---|---|
clientId | string (uuid) | yes |
talent | object | yes |
talent object:
| Field | Type | Required |
|---|---|---|
displayName | string, min 1 | yes |
contactName | string, min 1 | yes |
contactEmail | string (email) | yes |
hourlyRate | number, min 0 | yes |
currency | string, min 1, max 8 | yes |
hoursPerDay | number | yes |
shiftStart | string | yes |
shiftEnd | string | yes |
timezone | string, min 1 | yes |
status | "active" or "archived" or "pending" | no |
unpaidBreakHours | number, min 0 or null | no |
payoutHints | string or null | no |
paymentTermsOverride | string or null | no |
internalNotes | string or null | no |
colorTag | string or null | no |
Response 201: { assignment: Assignment }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
clerkOrgId | string, min 1 | yes |
talentId | string (uuid) | yes |
clientId | string (uuid) | yes |
status | "active" or "pending" or "ended" | yes |
talentDisplayName | string, min 1 or null | no |
clientDisplayName | string, min 1 or null | no |
createdAt | string | yes |
updatedAt | string | yes |
Get an assignment
GET /api/public/agency/assignments/{id}
Response 200: { assignment: Assignment }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
clerkOrgId | string, min 1 | yes |
talentId | string (uuid) | yes |
clientId | string (uuid) | yes |
status | "active" or "pending" or "ended" | yes |
talentDisplayName | string, min 1 or null | no |
clientDisplayName | string, min 1 or null | no |
createdAt | string | yes |
updatedAt | string | yes |
Update an assignment
PATCH /api/public/agency/assignments/{id}
Request body:
| Field | Type | Required |
|---|---|---|
status | "ended" or "active" or "pending" | yes |
Response 200: { assignment: Assignment }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
clerkOrgId | string, min 1 | yes |
talentId | string (uuid) | yes |
clientId | string (uuid) | yes |
status | "active" or "pending" or "ended" | yes |
talentDisplayName | string, min 1 or null | no |
clientDisplayName | string, min 1 or null | no |
createdAt | string | yes |
updatedAt | string | yes |