Invoices
Agency invoice request and response fields.
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": {} }.
Create an invoice with either talentId or clientId, not both and not neither.
List invoices
GET /api/public/agency/invoices
Response 200: { invoices: Invoice[] }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
kind | "studio_talent" or "agency_client" | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
clientId | string (uuid) or null | yes |
clientDisplayName | string or null | yes |
fromAt | string | yes |
toAt | string | yes |
currency | string | yes |
status | "draft" or "paid" or "void" | yes |
invoicePrefix | string | yes |
invoiceNumber | integer | yes |
displayNumber | string | yes |
subtotalCents | integer, min 0 | yes |
totalCents | integer, min 0 | yes |
notes | string or null | yes |
createdAt | string | yes |
lineItems | array of object | no |
lineItems items:
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
sourceKind | "timer" or "manual" | yes |
sourceId | string (uuid) or null | yes |
description | string | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
quantityHours | number, min 0 | yes |
unitRateCents | integer, min 0 | yes |
amountCents | integer, min 0 | yes |
sortOrder | integer, min 0 | yes |
Create an invoice
POST /api/public/agency/invoices
Request body:
| Field | Type | Required |
|---|---|---|
talentId | string (uuid) or null | no |
clientId | string (uuid) or null | no |
from | string, min 1 | yes |
to | string, min 1 | yes |
notes | string, max 4000 or null | no |
Response 201: { invoice: Invoice }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
kind | "studio_talent" or "agency_client" | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
clientId | string (uuid) or null | yes |
clientDisplayName | string or null | yes |
fromAt | string | yes |
toAt | string | yes |
currency | string | yes |
status | "draft" or "paid" or "void" | yes |
invoicePrefix | string | yes |
invoiceNumber | integer | yes |
displayNumber | string | yes |
subtotalCents | integer, min 0 | yes |
totalCents | integer, min 0 | yes |
notes | string or null | yes |
createdAt | string | yes |
lineItems | array of object | no |
lineItems items:
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
sourceKind | "timer" or "manual" | yes |
sourceId | string (uuid) or null | yes |
description | string | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
quantityHours | number, min 0 | yes |
unitRateCents | integer, min 0 | yes |
amountCents | integer, min 0 | yes |
sortOrder | integer, min 0 | yes |
Get an invoice
GET /api/public/agency/invoices/{id}
Response 200: { invoice: Invoice }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
kind | "studio_talent" or "agency_client" | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
clientId | string (uuid) or null | yes |
clientDisplayName | string or null | yes |
fromAt | string | yes |
toAt | string | yes |
currency | string | yes |
status | "draft" or "paid" or "void" | yes |
invoicePrefix | string | yes |
invoiceNumber | integer | yes |
displayNumber | string | yes |
subtotalCents | integer, min 0 | yes |
totalCents | integer, min 0 | yes |
notes | string or null | yes |
createdAt | string | yes |
lineItems | array of object | no |
lineItems items:
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
sourceKind | "timer" or "manual" | yes |
sourceId | string (uuid) or null | yes |
description | string | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
quantityHours | number, min 0 | yes |
unitRateCents | integer, min 0 | yes |
amountCents | integer, min 0 | yes |
sortOrder | integer, min 0 | yes |
Void an invoice
POST /api/public/agency/invoices/{id}/void
No request body.
Response 200: { invoice: Invoice }
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
kind | "studio_talent" or "agency_client" | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
clientId | string (uuid) or null | yes |
clientDisplayName | string or null | yes |
fromAt | string | yes |
toAt | string | yes |
currency | string | yes |
status | "draft" or "paid" or "void" | yes |
invoicePrefix | string | yes |
invoiceNumber | integer | yes |
displayNumber | string | yes |
subtotalCents | integer, min 0 | yes |
totalCents | integer, min 0 | yes |
notes | string or null | yes |
createdAt | string | yes |
lineItems | array of object | no |
lineItems items:
| Field | Type | Required |
|---|---|---|
id | string (uuid) | yes |
sourceKind | "timer" or "manual" | yes |
sourceId | string (uuid) or null | yes |
description | string | yes |
talentId | string (uuid) or null | yes |
talentDisplayName | string or null | yes |
quantityHours | number, min 0 | yes |
unitRateCents | integer, min 0 | yes |
amountCents | integer, min 0 | yes |
sortOrder | integer, min 0 | yes |
