---
title: "List envelopes"
method: GET
path: "/envelopes"
tags: ["Envelopes"]
---

# List envelopes

`GET /envelopes`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/envelopes`
- Auth: HTTP bearer

One page of the credential's workspace envelopes, newest first by `createdAt`. There is no query parameter that widens the list beyond the workspace the credential is bound to.

Each row carries the envelope's status, its document, and a signer roster reduced to id, name, email, and status. Field placement and per-signer timestamps are not in the list: fetch `GET /envelopes/{envelopeId}` for those.

`status` filters to a single envelope status, or `all`. A status value outside the enum is a `validation_error` (400), not an empty page.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'all' | 'draft' | 'sending' | 'pending' | 'completing' | 'completed' | 'declined' | 'voided' | 'expired'

## Response `200`

One page of envelopes.

- object
  - `data` EnvelopeSummary[], required
    - `id` string, required
    - `status` 'draft' | 'sending' | 'pending' | 'completing' | 'completed' | 'declined' | 'voided' | 'expired', required: Where the envelope is in its lifecycle. `sending` and `completing` are transient; `completed`, `declined`, `voided`, and `expired` are terminal.
    - `subject` string, required: Subject line of the signing invitation.
    - `signingOrder` 'parallel' | 'sequential', required
    - `template` EnvelopeTemplateProvenance, nullable, required
      - `id` string, nullable, required: Null after the source template is deleted.
      - `version` integer, required
    - `document` EnvelopeDocumentSummary, required: The document the envelope was built from, as the envelope routes publish it: the public id and the original upload filename, nothing else.
      - `id` string, required: Public document id.
      - `filename` string, required: The filename as uploaded.
    - `signers` SignerSummary[], required
      - `id` string, required: Public signer id.
      - `name` string, required
      - `email` string, email, required
      - `role` 'signer' | 'approver' | 'reviewer', required: What the recipient is asked to do. `signer` executes the document and must be assigned at least one field. `approver` approves or declines and may hold fields. `reviewer` acknowledges having read it and may hold none. Defaults to `signer`.
      - `status` 'pending' | 'sent' | 'viewed' | 'signed' | 'approved' | 'acknowledged' | 'declined', required: Where one recipient is. `pending` means not yet invited, which on a sequential envelope is normal for everyone behind the current turn. `signed`, `approved` and `acknowledged` are the three positive terminal states, one per role: a signer signs, an approver approves, a reviewer acknowledges.
    - `sentAt` string, date-time, nullable, required: When the worker mailed the invitations. Null until the envelope reaches `pending`.
    - `completedAt` string, date-time, nullable, required
    - `expiresAt` string, date-time, nullable, required: The signing deadline, set at creation from `expiresInDays`.
    - `createdAt` string, date-time, required
  - `pagination` Pagination, required: Where the returned page sits in the full result set.
    - `page` integer, required: The 1-based page returned.
    - `limit` integer, required: Items per page, as requested.
    - `total` integer, required: Total items matching the query.
    - `totalPages` integer, required: `ceil(total / limit)`.

## Other responses

- `400`: The request is malformed or the resource is in the wrong state for a synchronous check. Codes: `validation_error`, `invalid_body`, `invalid_parameter`, `invalid_idempotency_key`, `invalid_event_id`, `invalid_file`, `invalid_url`, `invalid_status`, `key_mismatch`, `no_signers`, `not_completed`, `envelope_exists`, `document_not_ready`, `upload_failed`.
- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested).
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

[API](https://skmtc.dev/inkseal/apis/inkseal-api.md) · [All operations](https://skmtc.dev/inkseal/apis/inkseal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inkseal/apis/inkseal-api/revisions/c440c981d578?raw)