Introduction

HR API

Overview

Attendance, shifts, leave, contracts, availability, and HR settings for the JWT organisation. userId on every person-scoped resource is the Directory user id. This service does not own people, timesheets, dashboards, or documents.

Integration guide: HR service docs

OpenAPI v0.1.0 · source openapi/hr.json

OpenAPI 3.0.0 · v0.1.0 · 51 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/health"

Unauthenticated liveness probe. Does not verify D1, R2, or JWT configuration.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/health"

Unauthenticated liveness probe. Alias of GET /health.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Settings

HR-specific settings for the JWT organisation (not Directory tenant data).

get/v1/settings

Get HR settings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/settings"

HR-specific settings for the JWT organisation (not the Directory tenant record).

Operation ID: getHrSettings

Responses

200
HR settings, or null before first provision
application/json

put/v1/settings

Create or update HR settings

Example request

curl -sS \
  -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/settings"

Creates or updates HR attendance policy windows (lateness grace and no-show threshold). Organisation profile lives in Directory.

Operation ID: upsertHrSettings

Request body(required)

application/jsonHrSettingsUpdate

Responses

200
Created or updated HR settings
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Shifts

Assigned roster. `userId` is a Directory user id.

get/v1/shifts

List assigned shifts

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/shifts"

Operational roster: a user assigned to a start/end at a work location. This is not Planning coverage demand.

Operation ID: listShifts

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—
userId	query	string	—
locationId	query	string	—
departmentId	query	string	—
startDate	query	string	—
endDate	query	string	—
status	query	string	—

Responses

200
Shifts
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/shifts

Create an assigned shift

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/shifts"

Operation ID: createShift

Request body(required)

application/jsonShiftCreate

Responses

201
Created shift
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/shifts/publish

Publish draft shifts

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/shifts/publish"

Operation ID: publishShifts

Request body(required)

application/jsonPublishShifts

Responses

200
Published shifts
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/shifts/{id}

Get a shift

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/shifts/example-id"

Operation ID: getShift

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Shift
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/shifts/{id}

Update a shift

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/shifts/example-id"

Operation ID: patchShift

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonShiftPatch

Responses

200
Updated shift
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/shifts/{id}

Cancel a shift

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/shifts/example-id"

Operation ID: cancelShift

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Cancelled shift
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Attendance

Clock-in, clock-out, breaks, and time entries. `userId` is a Directory user id.

get/v1/attendance/clock-pin/{userId}

Clock PIN status

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/attendance/clock-pin/example-id"

Directory `userId`. Returns whether a four-digit clock PIN is configured (not the PIN value). Members see their own record; managers see team members they can access.

Operation ID: getClockPinStatus

Parameters

Name	In	Type	Description
userId*	path	string	Directory user id.

Responses

200
Clock PIN status
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

put/v1/attendance/clock-pin/{userId}

Set clock PIN

Example request

curl -sS \
  -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/attendance/clock-pin/example-id"

Directory `userId`. Sets or replaces the employee four-digit numeric PIN used for clock-in and breaks. The employee or an HR manager with access may set it.

Operation ID: setClockPin

Parameters

Name	In	Type	Description
userId*	path	string	Directory user id.

Request body(required)

application/jsonClockPinSetRequest

Responses

200
Updated clock PIN status
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/attendance/clock-pin/{userId}/change

Change clock PIN

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/attendance/clock-pin/example-id/change"

Directory `userId`. Employee self-service: verifies `currentPin` and sets `newPin`. Managers reset PINs with PUT set (no current PIN required).

Operation ID: changeClockPin

Parameters

Name	In	Type	Description
userId*	path	string	Directory user id.

Request body(required)

application/jsonClockPinChangeRequest

Responses

200
Updated clock PIN status
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/time-entries/clock-in

Clock in

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/clock-in"

Creates an open time entry. Requires the employee four-digit clock PIN. The Worker generates `clockInAt` in UTC. Users may only have one open entry. Accepts Idempotency-Key.

Operation ID: clockIn

Request body(required)

application/jsonClockInRequest

Responses

201
Open time entry
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/time-entries/working-now

Who is currently clocked in

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/working-now"

Operation ID: workingNow

Responses

200
Employees currently clocked in
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/time-entries/{id}/clock-out

Clock out

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id/clock-out"

Operation ID: clockOut

Parameters

Name	In	Type	Description
id*	path	string	—

Request body

application/jsonClockOutRequest

Responses

200
Closed time entry
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/time-entries/{id}/breaks/start

Start a break

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id/breaks/start"

Operation ID: startBreak

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonBreakStartRequest

Responses

201
Started break
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/time-entries/{id}/breaks/{breakId}/end

End a break

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id/breaks/example-id/end"

Operation ID: endBreak

Parameters

Name	In	Type	Description
id*	path	string	—
breakId*	path	string	—

Request body(required)

application/jsonBreakEndRequest

Responses

200
Ended break
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/time-entries

List time entries

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries"

Operation ID: listTimeEntries

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—
userId	query	string	—
startDate	query	string	—
endDate	query	string	—

Responses

200
Time entries
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/time-entries/{id}

Get a time entry

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id"

Operation ID: getTimeEntry

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Time entry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/time-entries/{id}

Correct a time entry

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id"

Manager correction. Always writes TIME_ENTRY_CORRECTED to the audit log.

Operation ID: correctTimeEntry

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonTimeEntryPatch

Responses

200
Corrected time entry
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/time-entries/{id}/confirm-end

Confirm an unverified clock-out end

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/time-entries/example-id/confirm-end"

Manager action for forgotten clock-outs. A comment is required explaining why the employee worked past their scheduled end. After confirmation, hours count toward payroll.

Operation ID: confirmTimeEntryEnd

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonTimeEntryEndVerifyRequest

Responses

200
Verified time entry
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/attendance-exceptions

Attendance exceptions

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/attendance-exceptions"

Operation ID: listAttendanceExceptions

Parameters

Name	In	Type	Description
limit	query	integer	—
offset	query	integer	—
date	query	string	—

Responses

200
Exceptions
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/break-policies

List break entitlement policies

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/break-policies"

Age-based break rules used for contracts and attendance. Unpaid break minutes are deducted from paid hours when staff clock breaks.

Operation ID: listBreakPolicies

Responses

200
Break policies
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/break-policies

Create a break policy rule

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/break-policies"

Operation ID: createBreakPolicy

Request body(required)

application/jsonBreakPolicyWrite

Responses

201
Created break policy
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/break-policies/{id}

Update a break policy rule

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/hr/v1/break-policies/example-id"

Operation ID: updateBreakPolicy

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonobject

Responses

200
Updated break policy
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Contracts

Templates, issuance, electronic acceptance, and immutable signed copies.

get/v1/contract-templates

List contract templates

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contract-templates"

Operation ID: listContractTemplates

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—

Responses

200
Templates
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contract-templates

Create a contract template

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/contract-templates"

Content may include placeholders such as {{user.first_name}} and {{organisation.name}}.

Operation ID: createContractTemplate

Request body(required)

application/jsonContractTemplateWrite

Responses

201
Created template
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/contract-templates/{id}

Get a contract template

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contract-templates/example-id"

Operation ID: getContractTemplate

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Template
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/contract-templates/{id}

Update a contract template

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/contract-templates/example-id"

Saves name and content. Any change increments the template version. Existing issued contracts keep their original wording.

Operation ID: updateContractTemplate

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonContractTemplateWrite

Responses

200
Updated template
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/contracts

List contracts

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts"

Operation ID: listContracts

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—
userId	query	string	—
status	query	string	—

Responses

200
Contracts
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contracts

Generate a contract from a template

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/contracts"

Operation ID: createContract

Request body(required)

application/jsonContractCreate

Responses

201
Draft contract
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/contracts/{id}

Get a contract

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts/example-id"

Marks issued contracts as viewed when the user opens them.

Operation ID: getContract

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Contract
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contracts/{id}/issue

Issue a contract

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts/example-id/issue"

Operation ID: issueContract

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Issued contract
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contracts/{id}/sign

Electronically accept a contract

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts/example-id/sign"

Records signer IP, user agent, content hash, and timestamp. Signed contracts cannot be overwritten.

Operation ID: signContract

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Signed contract
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contracts/{id}/decline

Decline a contract

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts/example-id/decline"

Operation ID: declineContract

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Declined contract
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/contracts/{id}/void

Void a contract

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/contracts/example-id/void"

Operation ID: voidContract

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Voided contract
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Leave

Types, balances, requests, and approvals.

get/v1/leave-types

List leave types

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/leave-types"

Operation ID: listLeaveTypes

Responses

200
Leave types
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/leave-types

Create a leave type

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/leave-types"

Defines a leave category and default org entitlement (days). Contracts can override per employee.

Operation ID: createLeaveType

Request body(required)

application/jsonLeaveTypeCreate

Responses

201
Created leave type
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/leave-types/{id}

Update a leave type

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/leave-types/example-id"

Operation ID: updateLeaveType

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonLeaveTypePatch

Responses

200
Updated leave type
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/leave-balances

Leave balances

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/leave-balances"

Operation ID: listLeaveBalances

Parameters

Name	In	Type	Description
userId	query	string	—

Responses

200
Balances
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/leave-requests

List leave requests

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests"

Operation ID: listLeaveRequests

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—
status	query	string	—
userId	query	string	—

Responses

200
Leave requests
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/leave-requests

Request leave

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests"

Operation ID: createLeaveRequest

Request body(required)

application/jsonLeaveRequestCreate

Responses

201
Created request
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/leave-requests/{id}

Get a leave request

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests/example-id"

Operation ID: getLeaveRequest

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Leave request
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/leave-requests/{id}/approve

Approve leave

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests/example-id/approve"

Operation ID: approveLeave

Parameters

Name	In	Type	Description
id*	path	string	—

Request body

application/jsonLeaveDecision

Responses

200
Approved request
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/leave-requests/{id}/reject

Reject leave

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests/example-id/reject"

Operation ID: rejectLeave

Parameters

Name	In	Type	Description
id*	path	string	—

Request body

application/jsonLeaveDecision

Responses

200
Rejected request
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/leave-requests/{id}/cancel

Cancel a pending leave request

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/leave-requests/example-id/cancel"

Operation ID: cancelLeave

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Cancelled request
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Availability

Weekly availability per Directory `userId`.

get/v1/availability/{userId}

Get weekly availability

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/availability/example-id"

Directory `userId`. Members see their own record. Managers and admins can view team members they have access to.

Operation ID: getUserAvailability

Parameters

Name	In	Type	Description
userId*	path	string	Directory user id.

Responses

200
Weekly availability
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

put/v1/availability/{userId}

Replace weekly availability

Example request

curl -sS \
  -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/hr/v1/availability/example-id"

Directory `userId`. Only the employee can set or update their own availability.

Operation ID: putUserAvailability

Parameters

Name	In	Type	Description
userId*	path	string	Directory user id.

Request body(required)

application/jsonAvailabilityWrite

Responses

200
Updated weekly availability
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, USER_ALREADY_CLOCKED_IN, CONTRACT_IMMUTABLE, IDEMPOTENCY_CONFLICT, or similar.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Planning

Read models consumed by the Planning service binding (staffing terms).

get/v1/planning/staffing

Staffing terms for Planning

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/planning/staffing"

Returns contracted weekly hours and hourly pay from signed HR contracts (fallback: workforce weekly hours). Used by the Planning solver via service binding. Weekly availability is exposed on `/v1/availability/{userId}`.

Operation ID: listPlanningStaffing

Parameters

Name	In	Type	Description
from*	query	string	—
to*	query	string	—
locationId	query	string	—

Responses

200
Staffing terms
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Audit

Immutable HR audit log.

get/v1/audit

HR audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/hr/v1/audit"

Operation ID: listHrAudit

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—

Responses

200
Audit events
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json