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

{
  "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://.."
  }
}

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

Recipients can only be created when creating an 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, 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 endpoint.

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.

​
Attributes

​
id
string

The unique identifier for the recipient.

​
name
string(250)

The recipient’s full name.

​
email
string(250)

The recipient’s email address, used for identification and correspondence.

​
mobile
string(100)

The recipient’s mobile number, in E.164 format. Used for SMS delivery.

​
type
string

The recipient type: signer, viewer, or carbon-copy. Defaults to signer.

​
status
string

Read-only string representing the recipient’s current status.

Possible values: created, pending, sent, failed, completed, declined.

​
message
string(5000)

A custom message displayed to this recipient when they view the envelope. Overrides the envelope’s general message.

​
password
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.

​
muted
boolean

If true, Annature will not send any emails or SMS to this recipient.

​
order
integer

The recipient’s position in the signing order. Lower numbers act first.

​
declined_reason
string

If the recipient declined the envelope, this field may contain their reason.

​
created
string

Timestamp when the recipient was created (ISO 8601).

​
sent
string

Timestamp when the recipient was first sent the envelope. null if muted.

​
declined
string

Timestamp when the recipient declined the envelope.

​
completed
string

Timestamp when the recipient completed their actions.

​
redirects
object

Custom URLs for post-session navigation.

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

{
  "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://.."
  }
}