# 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

```json
{
  "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` — `listApprovals`
- `GET /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](integration-connections.html).