> ## 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 recipient object

A recipient represents an individual involved in the transaction of an envelope.

Recipients can only be created when [creating an envelope](/api-reference/envelopes/create-envelope). Each envelope must include at least one recipient to be valid.

## Recipient types

There are three recipient types: `signer`, `viewer`, and `carbon-copy`. Each type governs how the recipient interacts with the envelope and what actions are required for completion.

* `signer`: The default type. Recipients of this type must complete all assigned [fields](/api-reference/fields/field-object), such as signing or entering information. They may also decline the envelope unless it is already completed.
* `viewer`: These recipients must open the envelope and click a confirmation button to acknowledge they’ve reviewed the documents. They may decline prior to completion.
* `carbon-copy`: These recipients are passive observers and receive a completed copy of the envelope and certificate after the transaction is complete.

## Recipient statuses

The `status` property indicates a recipient’s progress toward completing their part in the envelope. Possible values:

* `created` — Recipient has just been created and is being prepared for dispatch.
* `pending` — Recipient is not yet eligible to sign, usually due to signing order constraints.
* `sent` — Recipient has been sent the envelope and is eligible to sign.
* `failed` — An error occurred while attempting to deliver the envelope (e.g. email bounced).
* `completed` — Recipient has completed their required actions.
* `declined` — Recipient has declined to sign the envelope.

> Carbon copy recipients do not have a `status` because they only receive the envelope after completion.

## Signing order

Use the `order` property to enforce a signing sequence. Recipients with a lower `order` value must complete their actions before recipients with a higher value are notified. You can mix sequential and parallel flows by reusing the same order number for multiple recipients.

## Muted recipients

Setting `muted` to `true` disables all automatic correspondence from Annature to the recipient.

This is commonly used when you want to control recipient communications manually, such as in a custom signing flow. Muted recipients must still have an email address, which is used to verify their identity during the signing process.

Signing tokens for muted recipients can be generated and managed via the [retrieve a signing token](/api-reference/recipients/retrieve-signing-token) endpoint.

<Note>
  If you choose to send your own email or SMS correspondence to recipients, you are responsible for maintaining accurate delivery logs and records. These records should demonstrate when the message was sent, to whom it was sent, and by what method.

  This is critical for ensuring enforceability under digital signature laws. If the validity of a signature is ever challenged, you may be asked to prove that the envelope was accessed and signed by the intended recipient. Without verifiable delivery and access records, the legal standing of the signature may be weakened.
</Note>

## Attributes

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

<ParamField path="name" type="string(250)">
  The recipient's full name.
</ParamField>

<ParamField path="email" type="string(250)">
  The recipient's email address, used for identification and correspondence.
</ParamField>

<ParamField path="mobile" type="string(100)">
  The recipient's mobile number, in E.164 format. Used for SMS delivery.
</ParamField>

<ParamField path="type" type="string">
  The recipient type: `signer`, `viewer`, or `carbon-copy`. Defaults to `signer`.
</ParamField>

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

  Possible values: `created`, `pending`, `sent`, `failed`, `completed`, `declined`.
</ParamField>

<ParamField path="message" type="string(5000)">
  A custom message displayed to this recipient when they view the envelope. Overrides the envelope’s general message.
</ParamField>

<ParamField path="password" type="string(100)">
  A passphrase the recipient must enter before viewing or signing the envelope.

  Once created, this will return `true` or `false` depending on whether a password is set.
</ParamField>

<ParamField path="muted" type="boolean">
  If `true`, Annature will not send any emails or SMS to this recipient.
</ParamField>

<ParamField path="order" type="integer">
  The recipient's position in the signing order. Lower numbers act first.
</ParamField>

<ParamField path="declined_reason" type="string">
  If the recipient declined the envelope, this field may contain their reason.
</ParamField>

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

<ParamField path="sent" type="string">
  Timestamp when the recipient was first sent the envelope. `null` if muted.
</ParamField>

<ParamField path="declined" type="string">
  Timestamp when the recipient declined the envelope.
</ParamField>

<ParamField path="completed" type="string">
  Timestamp when the recipient completed their actions.
</ParamField>

<ParamField path="redirects" type="object">
  Custom URLs for post-session navigation.

  <Expandable title="child attributes">
    <ResponseField name="session_completed" type="string">
      Where to redirect after recipient completes the envelope.
    </ResponseField>

    <ResponseField name="session_declined" type="string">
      Where to redirect after recipient declines the envelope.
    </ResponseField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash Endpoints theme={null}
  GET /v1/recipients/:id
  GET /v1/recipients/:id/token
  POST /v1/recipients/:id/resend-email
  POST /v1/recipients/:id/resend-sms
  PUT /v1/recipients/:id
  DELETE /v1/recipients/:id
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "255e591c2c9fe1bc99be1ec03075b402",
    "name": "Ted Annature",
    "email": "ted@annature.com.au",
    "mobile": "+61422000000",
    "type": "signer",
    "status": "sent",
    "message": "Lorem ipsum dolor sit amet.",
    "password": true,
    "muted": false,
    "order": 1,
    "declined_reason": "Lorem ipsum dolor sit amet.",
    "created": "2019-12-17T05:30:00Z",
    "sent": "2019-12-17T05:30:00Z",
    "declined": "2019-12-17T05:30:00Z",
    "completed": "2019-12-17T05:30:00Z",
    "redirects": {
      "session_completed": "https://..",
      "session_declined": "https://.."
    }
  }
  ```
</ResponseExample>