x-cpod-domain: approvals

Approvals

Approval requests and steps — the workflow surface.

Try in explorer client.approvals

ApprovalRequest

A request requiring approvals.

REST path/api/v1/approvals/requests

Operations

listgetcreatesubmitcancel

SDK

// list — returns only your records; add filters/search:
await client.approvals.requests.list()

// create:
await client.approvals.requests.create({
  id: "rec_01HXEXAMPLE",
  tenant_id: "example tenant_id",
  created_at: "2026-01-01T00:00:00Z",
  updated_at: "2026-01-01T00:00:00Z",
  app_id: "example app_id",
  created_by: "rec_01HXEXAMPLE",
})

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
entity_type	string	EDM entity type being approved (e.g. 'Expense', 'LeaveRequest', 'Contract', 'PurchaseOrder').
entity_id	uuid	UUID of the specific entity instance awaiting approval.
requested_by_id	uuid	UUID of the Person who initiated this approval request.
title	string	Human-readable title summarising what is being approved.
description	string	Optional longer description or justification for the approval request.
status	string	Overall status of the approval request.
current_step_index	number	Zero-based index of the currently active approval step.
total_steps	number	Total number of approval steps required before the request is fully approved.
due_at	date-time	ISO 8601 deadline by which the approval must be completed. Null if no deadline applies.
completed_at	date-time	ISO 8601 timestamp when the approval reached a terminal state (approved, rejected, cancelled, or expired). Null while still pending.
requester_id	uuid	User who initiated this approval request.
tags	json	Free-form tags categorising the request (e.g. ['leave', 'q2']).

ApprovalStep

A step in an ApprovalRequest's chain.

REST path/api/v1/approvals/steps

Operations

listgetapprovereject

SDK

// list — returns only your records; add filters/search:
await client.approvals.steps.list()

Field	Type	Description
id*	uuid	Server-assigned ULID with type prefix (e.g. per_…).
tenant_id*	string	Tenant scope — auto-stamped from the caller's JWT.
app_id	string	App scope. Stamped ONLY when the caller's JWT was minted for a specific Application (integration API keys). Absent for human-user sessions. Filters reads when present.
created_at*	date-time	Server stamp.
updated_at*	date-time	Server stamp; updated on every patch.
created_by	uuid	Person id from the caller's JWT (sub).
updated_by	uuid	Person id from the last writer's JWT (sub).
source	string	Provenance tag — defaults to 'edm'.
source_type	enum	Where the write originated. Defaults to 'api'.`frontendbackendserversystemapi`
is_deleted	boolean	Soft-delete flag. Excluded from default list queries.
deleted_at	date-time	Stamped when soft-deleted; null otherwise.
deleted_by	uuid	Person id who soft-deleted; null otherwise.
schema_version	number	Document schema version. Bumped on incompatible writes.
approval_request_id	uuid	UUID of the parent ApprovalRequest.
step_index	number	Zero-based position of this step in the approval chain.
approver_id	uuid	UUID of the Person assigned to decide on this step.
status	string	Current state of this step.
decision	string	The approver's explicit decision. Null while the step is still pending.
comment	string	Optional comment or justification left by the approver alongside their decision.
decided_at	date-time	ISO 8601 timestamp when the approver made their decision. Null while still pending.
delegated_to_id	uuid	UUID of the Person this step was delegated to. Null unless status is 'delegated'.
request_id	uuid	Parent approval request this step belongs to.
delegated	boolean	True once the step has been reassigned to another approver.

Docs

ApprovalRequest

ApprovalStep