Approvals API
The Approvals API is deliberately read-only for API Clients. Integrations may observe approval state and react to the outcome, but they may not approve, reject, delegate, or otherwise cast a human decision.
Why approval actions are excluded
An API Client is a durable organization principal, not a named person. Formal approval must preserve a clear accountable human actor. Supplying a member subject does not turn the API Client into that member and never authorizes an approval action.
Roles
An approval is visible only when the API Client has the Role required for the underlying resource—for example, Finance for a financial approval or Manager for a project approval. HR approvals require HR. Field-level restrictions continue to apply.
Approval object
{
"object": "approval",
"id": "apr_01J8RB1JK6VZ6NSS8A2K5ZCBR9",
"type": "invoice",
"status": "pending",
"resource": {"type": "invoice", "id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S"},
"requested_at": "2026-08-22T10:30:00Z",
"decided_at": null,
"decision": null,
"version": 1
}
Named approver identities are returned only where the organization's people-data policy permits.
List and get approvals
GET /v1/approvals—listApprovalsGET /v1/approvals/{approval_id}—getApproval
Filters: status, type, resource_type, resource_id, requested_after, updated_after, limit, and after.
Observe changes
Use approval.created and approval.updated webhooks to avoid polling. Consumers must still fetch the current approval before acting because webhook delivery is at least once and can arrive after a later change.
Unsupported operations
There are no API Client endpoints for approve, reject, request changes, delegate, or substitute approver. Those actions require a named user in an interactive Eos surface. Attempts return API_PRINCIPAL_NOT_ALLOWED.
Common errors
APPROVAL_NOT_FOUND, APPROVAL_ACCESS_DENIED, and API_PRINCIPAL_NOT_ALLOWED.
Next: Integration Connections API.