Approvals API

15 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/approvals/delegations

List out-of-office cover

Current and upcoming cover involving the caller; hr_admins and owners see everyone's with `all=true`.

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
all	query	enum	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • fromobjectrequired

    • membershipIdstring (uuid)required
    • namestringrequired
  • toobjectrequired

    • membershipIdstring (uuid)required
    • namestringrequired
  • startsOnstring (date)required
  • endsOnstring (date)required
  • subjectTypesarray of string or nullrequired
  • activebooleanrequired
  • createdAtstring (date-time)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/approvals/delegations

Set out-of-office cover

While active, the delegate also receives the member's approval tasks. hr_admins may set it for anyone.

Access

Any signed-in member (own data only)

Request body

application/json, object, required

• fromMembershipIdstring (uuid)
• toMembershipIdstring (uuid)required
• startsOnstring (date)required
• endsOnstring (date)required
• subjectTypesarray of string or null

Responses

201 Success. object

• idstring (uuid)required
• fromobjectrequired

  • membershipIdstring (uuid)required
  • namestringrequired
• toobjectrequired

  • membershipIdstring (uuid)required
  • namestringrequired
• startsOnstring (date)required
• endsOnstring (date)required
• subjectTypesarray of string or nullrequired
• activebooleanrequired
• createdAtstring (date-time)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found

DELETE/api/v1/approvals/delegations/{id}

Remove out-of-office cover

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found

GET/api/v1/approvals/people

List members who can approve or cover

Active members of the organisation (name only), for delegate and approver pickers.

Access

Any signed-in member (own data only)

Responses

200 Success. object

• itemsarray of objectrequired

  • membershipIdstring (uuid)required
  • namestringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

GET/api/v1/approvals/policies

List approval policies per request type

Types without a stored policy show the built-in default chain.

Access

Permission policies:read

Responses

200 Success. object

• typesarray of objectrequired

  • subjectTypestringrequired
  • labelstringrequired
  • installedbooleanrequired
  • ownerOnlybooleanrequired
  • canEditbooleanrequired
  • policiesarray of objectrequired

    • idstring (uuid) or nullrequired
    • namestringrequired
    • conditionobject or nullrequired

      • amountGteinteger

        min 1 · max 100000000000

      • typeCodesarray of string
    • priorityintegerrequired

      min -9007199254740991

    • isDefaultbooleanrequired
    • builtInbooleanrequired
    • stepsarray of objectrequired

      • approverRulestringrequired
      • labelstringrequired
      • escalateAfterDaysintegerrequired

        min -9007199254740991

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

PUT/api/v1/approvals/policies/{subjectType}

Replace the approval policies of one request type

Exactly one policy must have no condition (the default). Requests already submitted keep their chain. Policies for payroll runs and profile changes (bank details) are owner-only.

Access

Permission policies:update

Parameters

Name	In	Type	Required
subjectType	path	string	yes

Request body

application/json, object, required

• policiesarray of objectrequired

  • namestringrequired

    min length 1 · max length 80

  • conditionobject or null

    • amountGteinteger

      min 1 · max 100000000000

    • typeCodesarray of string
  • priorityinteger

    min 0 · max 1000 · default 0

  • stepsarray of objectrequired

    • approverRulestringrequired
    • escalateAfterDaysinteger

      min 0 · max 60 · default 3

Responses

200 Success. object

• subjectTypestringrequired
• policiesarray of objectrequired

  • idstring (uuid) or nullrequired
  • namestringrequired
  • conditionobject or nullrequired

    • amountGteinteger

      min 1 · max 100000000000

    • typeCodesarray of string
  • priorityintegerrequired

    min -9007199254740991

  • isDefaultbooleanrequired
  • builtInbooleanrequired
  • stepsarray of objectrequired

    • approverRulestringrequired
    • labelstringrequired
    • escalateAfterDaysintegerrequired

      min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found

GET/api/v1/approvals/requests

List my requests

Requests the caller submitted, newest first.

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
limit	query	integer	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • subjectTypestringrequired
  • subjectLabelstringrequired
  • titlestringrequired
  • statusenumrequired

    one of "pending", "approved", "rejected", "withdrawn"

  • submittedAtstring (date-time)required
  • decidedAtstring (date-time) or nullrequired
  • waitingOnstring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

GET/api/v1/approvals/requests/{id}

Get a request with its approval chain

Visible to the requester, approvers, delegates while their task is open, owners and hr_admins (not payroll runs), and whoever the module's `canRead` allows.

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• idstring (uuid)required
• subjectTypestringrequired
• subjectLabelstringrequired
• titlestringrequired
• statusenumrequired

  one of "pending", "approved", "rejected", "withdrawn"

• policyNamestringrequired
• submittedAtstring (date-time)required
• decidedAtstring (date-time) or nullrequired
• requesterobjectrequired

  • namestringrequired
• summaryobject or nullrequired

  • titlestringrequired
  • linesarray of objectrequired

    • labelstringrequired
    • valuestringrequired
  • contextarray of objectrequired

    • labelstringrequired
    • valuestringrequired
• linkstringrequired
• stepsarray of objectrequired

  • positionintegerrequired

    min -9007199254740991

  • labelstringrequired
  • statusenumrequired

    one of "waiting", "active", "approved", "rejected", "skipped"

  • skipReasonstring | nullrequired
  • fallbackbooleanrequired
  • escalatedbooleanrequired
  • tasksarray of objectrequired

    • idstring (uuid)required
    • assigneestringrequired
    • onBehalfOfstring | nullrequired
    • originenumrequired

      one of "resolved", "delegated", "escalated", "reassigned"

    • statusenumrequired

      one of "pending", "approved", "rejected", "superseded"

    • decidedAtstring (date-time) or nullrequired
    • commentstring | nullrequired
    • selfApprovedbooleanrequired
• commentsarray of objectrequired

  • idstring (uuid)required
  • authorstringrequired
  • bodystringrequired
  • createdAtstring (date-time)required
• viewerobjectrequired

  • myTaskIdstring (uuid) or nullrequired
  • canWithdrawbooleanrequired
  • canCommentbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required
• 404 not_found

POST/api/v1/approvals/requests/{id}/comments

Comment on a request

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• bodystringrequired

  min length 1 · max length 500

Responses

201 Success. object

• idstring (uuid)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found

POST/api/v1/approvals/requests/{id}/withdraw

Withdraw my pending request

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

200 Success. object

• requestIdstring (uuid)required
• status"withdrawn"required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found
• 409 already_decided

GET/api/v1/approvals/tasks

List my open approval tasks

Pending tasks assigned to the caller, including delegated, escalated and reassigned ones.

Access

Any signed-in member (own data only)

Responses

200 Success. object

• itemsarray of objectrequired

  • taskIdstring (uuid)required
  • requestIdstring (uuid)required
  • subjectTypestringrequired
  • subjectLabelstringrequired
  • titlestringrequired
  • requesterobjectrequired

    • namestringrequired
  • submittedAtstring (date-time)required
  • dueOnstring (date) or nullrequired
  • overdueDaysintegerrequired

    min -9007199254740991

  • originenumrequired

    one of "resolved", "delegated", "escalated", "reassigned"

  • onBehalfOfstring | nullrequired
  • inlinebooleanrequired
  • stepobjectrequired

    • positionintegerrequired

      min -9007199254740991

    • ofintegerrequired

      min -9007199254740991

    • labelstringrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/approvals/tasks/{id}/decision

Approve or reject a task

Idempotent: repeating the same decision returns `replayed: true`. A task that someone else already decided answers 409 `already_decided` with who decided and when.

Access

Permission approval_tasks:decide

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• decisionenumrequired

  one of "approve", "reject"

• commentstring or null

  max length 500

Responses

200 Success. object

• taskIdstring (uuid)required
• requestIdstring (uuid)required
• outcomeenumrequired

  one of "approved", "rejected"

• requestStatusenumrequired

  one of "pending", "approved", "rejected", "withdrawn"

• replayedbooleanrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 already_decided

POST/api/v1/approvals/tasks/{id}/reassign

Reassign a pending task

Access

Permission approval_tasks:reassign

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Request body

application/json, object, required

• toMembershipIdstring (uuid)required
• reasonstringrequired

  min length 1 · max length 500

Responses

200 Success. object

• taskIdstring (uuid) or nullrequired
• requestIdstring (uuid)required

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required
• 404 not_found
• 409 already_decided

POST/api/v1/approvals/tasks/decisions

Approve or reject several tasks

Each task is decided in its own transaction; the result lists the outcome per task.

Access

Permission approval_tasks:decide

Request body

application/json, object, required

• taskIdsarray of string (uuid)required
• decisionenumrequired

  one of "approve", "reject"

• commentstring or null

  max length 500

Responses

200 Success. object

• resultsarray of objectrequired

  • taskIdstring (uuid)required
  • okbooleanrequired
  • requestStatusenum or nullrequired

    one of "pending", "approved", "rejected", "withdrawn"

  • codestring | nullrequired
  • messagestring | nullrequired

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, forbidden, mfa_enrolment_required

GET/api/v1/inbox

My work to do

Actionable items from every source (approvals, reminders, setup, payroll due), overdue first, then by due date, then by age. `sources` says which sources are not set up yet.

Access

Any signed-in member (own data only)

Responses

200 Success. object

• todaystring (date)required
• itemsarray of objectrequired

  • idstringrequired
  • sourcestringrequired
  • kindstringrequired
  • titlestringrequired
  • concernsstring | nullrequired
  • detailstring | nullrequired
  • dueOnstring (date) or nullrequired
  • overdueDaysintegerrequired

    min -9007199254740991

  • createdAtstring (date-time)required
  • hrefstringrequired
  • actionLabelstringrequired
  • taskobject or nullrequired

    • idstring (uuid)required
    • requestIdstring (uuid)required
    • subjectTypestringrequired
    • inlinebooleanrequired
    • originenumrequired

      one of "resolved", "delegated", "escalated", "reassigned"

    • onBehalfOfstring | nullrequired
• sourcesarray of objectrequired

  • idstringrequired
  • labelstringrequired
  • statusenumrequired

    one of "ready", "not_set_up"

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required