> ## Documentation Index
> Fetch the complete documentation index at: https://docs.annature.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# The Envelope object

An envelope is the core resource in Annature. It represents a single transaction between one or more [recipients](/api-reference/recipients/recipient-object), and contains one or more [documents](/api-reference/documents/document-object). Envelopes also include metadata about the sender, security settings, and the overall status of the transaction.

Not all recipients are required to sign the documents in an envelope. For example, a recipient with the `viewer` type is only required to view the documents.\
For more information about recipient types and their roles, refer to the [recipients](/api-reference/recipients/recipient-object) section.

Envelopes are always created and sent from a specific account, using the `account_id` property. The envelope will automatically inherit the branding configuration of the [group](/api-reference/groups/group-object) that the account belongs to. If no group is assigned, the organisation's default branding will be used.

### Envelope statuses

The `status` property indicates the current state of the envelope. Valid values include:

* `draft` – The envelope has been created but not yet sent. Draft envelopes can be sent programmatically using the [Send envelope](/api-reference/envelopes/send-envelope) endpoint or from the Annature dashboard.
* `created` – The envelope is in the process of being prepared for delivery. This is a short-lived transitional state immediately before sending.
* `sent` – The envelope has been sent and is awaiting action from one or more recipients.
* `completed` – All recipients have completed their actions. The finalised document and certificate of completion are available for download.
* `voided` – The envelope was cancelled by the sender before completion. Recipients can no longer view or interact with it.

### Downloadable copies

Envelopes expose several downloadable assets through temporary URLs, valid for 60 minutes by default.

* **original** – The combined document exactly as it was uploaded, before any fields (e.g. signatures, dates) were applied.
* **master** – The live, up-to-date version of the envelope with all completed actions applied. This is null while the envelope is still in `created` status.
* **certificate** – A certificate of completion PDF. Available only once the envelope is completed.
* **combined** – A single PDF file containing the master copy of the envelope and the certificate of completion appended to the end. This is available only once the envelope is completed.

### Envelope sharing and group visibility

Envelope visibility is controlled by the sender’s role, group membership, and the `shared` property on the envelope.

* **Administrators** can view and manage all envelopes across the organisation, regardless of sender or group.
* **Standard users** can only see envelopes they have personally sent — unless additional access is granted through group sharing.

When a standard user is assigned to a [group](/api-reference/groups/group-oObject), they gain access to any envelope sent by another member of that group — but **only** if the envelope is marked as `shared`.

By default, standard users can choose whether an envelope is shared with their group or kept private. However, default sharing behavior or forced sharing rules can be configured at the account level via the Annature dashboard.

> Each account can belong to **only one group**. Cross-group sharing is not supported.

This structure allows organisations to reflect real-world teams and permission boundaries — ensuring that users only access envelopes relevant to their role or department.

## Attributes

<ParamField path="id" type="string">
  The unique identifier for the envelope.
</ParamField>

<ParamField path="name" type="string(250)">
  The name of the envelope. Appears in the subject line of emails sent to recipients and in the Annature dashboard.
</ParamField>

<ParamField path="message" type="string(5000)">
  The message body shown in recipient emails and when viewing the envelope.
</ParamField>

<ParamField path="status" type="string">
  Read-only string representing the envelope’s current status.

  Possible values: `draft`, `created`, `sent`, `completed`, `voided`.
</ParamField>

<ParamField path="shared" type="boolean">
  Indicates whether the envelope is shared with other accounts in the same group as the sender.
</ParamField>

<ParamField path="created" type="string">
  Timestamp when the envelope was created (ISO 8601 format).
</ParamField>

<ParamField path="sent" type="string">
  Timestamp when the envelope was sent to recipients (ISO 8601 format).
</ParamField>

<ParamField path="voided" type="string">
  Timestamp when the envelope was voided by the sender (ISO 8601 format).
</ParamField>

<ParamField path="declined" type="string">
  Timestamp when a recipient declined the envelope (ISO 8601 format).
</ParamField>

<ParamField path="completed" type="string">
  Timestamp when the envelope was fully completed (ISO 8601 format).
</ParamField>

<ParamField path="original" type="string">
  Temporary URL to download the original (unmodified) copy of the envelope.

  This link is valid for 60 minutes and will return a `403 Forbidden` response after expiry.
</ParamField>

<ParamField path="master" type="string">
  Temporary URL to download the master (live) version of the envelope.

  This value is `null` if the envelope is still in the `created` status.

  Link is valid for 60 minutes and will return a `403 Forbidden` response after expiry.
</ParamField>

<ParamField path="certificate" type="string">
  Temporary URL to download the envelope’s certificate of completion.

  Only present when the envelope status is `completed`.

  Link is valid for 60 minutes and will return a `403 Forbidden` response after expiry.
</ParamField>

<ParamField path="combined" type="string">
  A temporary endpoint used to download a merged PDF that includes both the master copy of the envelope and the certificate of completion.

  Only present when the envelope status is `completed`.

  The link is valid for 60 minutes and will return a `403 Forbidden` response after expiry.
</ParamField>

<ParamField path="account_id" type="string">
  The unique identifier of the account that created (and sent) the envelope.
</ParamField>

<ParamField path="group_id" type="string">
  The group assigned to the envelope. If `shared` is `true`, other accounts in this group can view and manage the envelope.
</ParamField>

<ParamField path="recipients" type="array">
  A list of recipient objects associated with the envelope.

  There must be at least one recipient with a type of `signer`.
</ParamField>

<ParamField path="metadata" type="object">
  A set of key–value pairs that can be attached to the envelope.

  Use this to store custom metadata in a structured format.
</ParamField>

<RequestExample>
  ```bash Endpoints theme={null}
  GET /v1/envelopes
  GET /v1/envelopes/:id
  POST /v1/envelopes
  POST /v1/envelopes/:id/void
  PUT /v1/envelopes/:id
  DELETE /v1/envelopes/:id
  ```
</RequestExample>

<ResponseExample>
  ```bash Envelope Object theme={null}
  {
    "id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
    "name": "Non disclosure agreement",
    "message": "Lorem ipsum dolor sit amet.",
    "status": "sent",
    "shared": false,
    "created": "2019-12-17T05:30:00Z",
    "sent": "2019-12-17T05:30:00Z",
    "voided": "2019-12-17T05:30:00Z",
    "declined": "2019-12-17T05:30:00Z",
    "completed": "2019-12-17T05:30:00Z",
    "master": "https://annature..",
    "certificate": "https://annature..",
    "combined": "https://annature..",
    "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
    "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
    "recipients": [],
    "metadata": {}
  }
  ```
</ResponseExample>