Organisation

Departments, job titles, branches, employment types, pay grades, shifts and holidays. These are workspace configuration rather than personal data, so they share one pair of scopes: org:read and org:write.

List departments

GET/v1/departments

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	active · inactive	No	Only records in this state.

Responses

Status	Meaning
200	A page of departments.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a department

POST/v1/departments

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created department.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a department

GET/v1/departments/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The department.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such department in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a department

PATCH/v1/departments/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated department.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such department in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a department

DELETE/v1/departments/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted department.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such department in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List designations

GET/v1/designations

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	active · inactive	No	Only records in this state.

Responses

Status	Meaning
200	A page of designations.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a designation

POST/v1/designations

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created designation.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a designation

GET/v1/designations/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The designation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such designation in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a designation

PATCH/v1/designations/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated designation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such designation in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a designation

DELETE/v1/designations/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted designation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such designation in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List branches

GET/v1/branches

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	active · inactive	No	Only records in this state.

Responses

Status	Meaning
200	A page of branches.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a branch

POST/v1/branches

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created branch.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a branch

GET/v1/branches/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The branch.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such branch in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a branch

PATCH/v1/branches/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated branch.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such branch in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a branch

DELETE/v1/branches/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted branch.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such branch in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List employment types

GET/v1/employment_types

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.

Responses

Status	Meaning
200	A page of employment types.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a employment type

POST/v1/employment_types

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created employment type.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a employment type

GET/v1/employment_types/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The employment type.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employment type in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a employment type

PATCH/v1/employment_types/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated employment type.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employment type in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a employment type

DELETE/v1/employment_types/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted employment type.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such employment type in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List pay grades

GET/v1/pay_grades

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.

Responses

Status	Meaning
200	A page of pay grades.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a pay grade

POST/v1/pay_grades

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created pay grade.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a pay grade

GET/v1/pay_grades/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The pay grade.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such pay grade in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a pay grade

PATCH/v1/pay_grades/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated pay grade.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such pay grade in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a pay grade

DELETE/v1/pay_grades/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted pay grade.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such pay grade in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List shifts

GET/v1/shifts

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	active · inactive	No	Only records in this state.

Responses

Status	Meaning
200	A page of shifts.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a shift

POST/v1/shifts

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created shift.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a shift

GET/v1/shifts/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The shift.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such shift in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a shift

PATCH/v1/shifts/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated shift.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such shift in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a shift

DELETE/v1/shifts/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted shift.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such shift in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.

List holidays

GET/v1/holidays

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
year	integer	No	Only holidays in this calendar year.
branch_id	string	No	Only holidays observed at this branch.

Responses

Status	Meaning
200	A page of holidays.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a holiday

POST/v1/holidays

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The created holiday.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A conflicting record exists, or a referenced id does not.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a holiday

GET/v1/holidays/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The holiday.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such holiday in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a holiday

PATCH/v1/holidays/{id}

Only the fields present in the body are changed.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated holiday.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such holiday in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Delete a holiday

DELETE/v1/holidays/{id}

Permanent — these records have no soft-delete state. Refused with 409 while anything still references the record.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The deleted holiday.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such holiday in this workspace.
409	The record is still referenced by other records.
429	Rate limit exceeded. See the RateLimit-* headers.