# signing.envelopes.list

List signature envelopes with their status, linked record, recipients' progress, and key dates. Filter by status (including open and attention), templateKey, subjectType and subjectId (for example contractor), or a title/recipient search. Each envelope says whether it is waiting for your own signature (awaitingMe) and, when it is, gives signUrl: the page where you sign it yourself. Pass awaitingMe: true to list only those. Signing only happens there; agents can't sign for you. An envelope made from a job gives the job's title and version and its pay as the agreement states it (pay, rateBasis job or one_off). counts: true also returns how many envelopes each status filter holds.

`GET | POST /api/v1/accounting/signing.envelopes.list`

Permissions: `accounting:read` · Roles: admin, finance

Not available over MCP: Accountants' supporting originals grant isn't offered over MCP yet: phase 1 is read and comment only.

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `status` | enum |  | Only include records with this status. One of: `draft`, `sent`, `in_progress`, `changes_requested`, `completing`, `completed`, `declined`, `voided`, `expired`, `open`, `attention`. |
| `templateKey` | string |  | Matches ^[a-z][a-z0-9-]{1,60}$. |
| `subjectType` | enum |  | The kind of record this is about, such as entry, invoice or mail. One of: `contractor`, `party`, `invoice`. |
| `subjectId` | string |  | The ID of the record this is about. 1–200 characters. |
| `query` | string |  | Text to search for. at most 200 characters. |
| `awaitingMe` | boolean |  |  |
| `counts` | boolean |  |  |
| `limit` | integer |  | How many results to return at most. 1 to 100. Default `30`. |
| `offset` | integer |  | How many results to skip, for the next page of a list. 0 to 100000. Default `0`. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/signing.envelopes.list \
  -H "Authorization: Bearer $OATMILK_API_KEY"
```

Reference page: https://app.getoatmilk.com/docs/api/signing.envelopes.list