Recipients API

This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference, see the OpenAPI Reference.

Recipient Object

{
  "id": 123,
  "envelopeId": "clu1abc2def3ghi4jkl",
  "email": "signer@example.com",
  "name": "John Doe",
  "role": "SIGNER",
  "signingOrder": 1,
  "token": "abc123...",
  "signedAt": "2024-01-15T10:30:00Z",
  "readStatus": "OPENED",
  "signingStatus": "SIGNED",
  "sendStatus": "SENT"
}

Field	Type	Description
`id`	number	Unique recipient identifier
`envelopeId`	string	ID of the associated envelope
`email`	string	Recipient's email address
`name`	string	Recipient's display name
`role`	string	Recipient role (see below)
`signingOrder`	number \| null	Order in sequential signing
`token`	string	Unique token for signing URL
`signedAt`	string \| null	ISO timestamp when signed
`readStatus`	string	`NOT_OPENED` or `OPENED`
`signingStatus`	string	`NOT_SIGNED`, `SIGNED`, or `REJECTED`
`sendStatus`	string	`NOT_SENT` or `SENT`

Recipient Roles

Role	Description
`SIGNER`	Must sign the document. Required fields must be completed.
`APPROVER`	Must approve the document before signers can proceed.
`VIEWER`	Can view the document but takes no action.
`CC`	Receives a copy of the completed document. No action required.
`ASSISTANT`	Can fill in fields on behalf of another recipient.

Get Recipient

Retrieve a single recipient by ID.

GET /api/v2/envelope/recipient/{recipientId}

Example

curl "https://app.documenso.com/api/v2/envelope/recipient/789" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"

const response = await fetch(
  'https://app.documenso.com/api/v2/envelope/recipient/789',
  {
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
    },
  },
);

const recipient = await response.json();

Response

Returns the full recipient object including fields.

Create Recipients

Add one or more recipients to an envelope.


POST /api/v2/envelope/recipient/create-many

Request Body

Field	Type	Required	Description
`envelopeId`	string	Yes	ID of the envelope to add recipients to
`data`	array	Yes	Array of recipient objects

Each item in the data array:

Field	Type	Required	Description
`email`	string	Yes	Recipient's email address
`name`	string	Yes	Recipient's display name (max 255 chars)
`role`	string	Yes	Recipient role (see Recipient Roles above)
`signingOrder`	number	No	Position in sequential signing
`accessAuth`	string[]	No	Access authentication types
`actionAuth`	string[]	No	Action authentication types

Example

curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "clu1abc2def3ghi4jkl",
    "data": [
      {
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "signingOrder": 1
      },
      {
        "email": "approver@example.com",
        "name": "Jane Smith",
        "role": "APPROVER",
        "signingOrder": 0
      }
    ]
  }'

const response = await fetch(
  'https://app.documenso.com/api/v2/envelope/recipient/create-many',
  {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      envelopeId: 'clu1abc2def3ghi4jkl',
      data: [
        {
          email: 'signer@example.com',
          name: 'John Doe',
          role: 'SIGNER',
          signingOrder: 1,
        },
        {
          email: 'approver@example.com',
          name: 'Jane Smith',
          role: 'APPROVER',
          signingOrder: 0,
        },
      ],
    }),
  },
);

const { data: recipients } = await response.json();

Response

{
  "data": [
    {
      "id": 789,
      "envelopeId": "clu1abc2def3ghi4jkl",
      "email": "signer@example.com",
      "name": "John Doe",
      "role": "SIGNER",
      "signingOrder": 1,
      "token": "abc123def456",
      "signedAt": null,
      "readStatus": "NOT_OPENED",
      "signingStatus": "NOT_SIGNED",
      "sendStatus": "NOT_SENT"
    },
    {
      "id": 790,
      "envelopeId": "clu1abc2def3ghi4jkl",
      "email": "approver@example.com",
      "name": "Jane Smith",
      "role": "APPROVER",
      "signingOrder": 0,
      "token": "def456ghi789",
      "signedAt": null,
      "readStatus": "NOT_OPENED",
      "signingStatus": "NOT_SIGNED",
      "sendStatus": "NOT_SENT"
    }
  ]
}

Update Recipients

Update one or more recipients on an envelope. Only available for envelopes that are not yet completed.

POST /api/v2/envelope/recipient/update-many

Request Body

Field	Type	Required	Description
`envelopeId`	string	Yes	ID of the envelope containing the recipients
`data`	array	Yes	Array of recipient update objects

Each item in the data array:

Field	Type	Required	Description
`id`	number	Yes	ID of the recipient to update
`email`	string	No	New email address
`name`	string	No	New display name (max 255 chars)
`role`	string	No	New recipient role
`signingOrder`	number	No	New position in sequential signing
`accessAuth`	string[]	No	Access authentication types
`actionAuth`	string[]	No	Action authentication types

Example

curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeId": "clu1abc2def3ghi4jkl",
    "data": [
      {
        "id": 789,
        "name": "Jane Doe",
        "signingOrder": 2
      }
    ]
  }'

const response = await fetch(
  'https://app.documenso.com/api/v2/envelope/recipient/update-many',
  {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      envelopeId: 'clu1abc2def3ghi4jkl',
      data: [
        {
          id: 789,
          name: 'Jane Doe',
          signingOrder: 2,
        },
      ],
    }),
  },
);

const { data: updatedRecipients } = await response.json();

Response

Returns the updated recipient objects in a data array.

Delete Recipient

Remove a recipient from an envelope. Only available for envelopes that are not yet completed.


POST /api/v2/envelope/recipient/delete

Request Body

Field	Type	Required	Description
`recipientId`	number	Yes	ID of the recipient to remove

Example

curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/delete" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": 789
  }'

const response = await fetch(
  'https://app.documenso.com/api/v2/envelope/recipient/delete',
  {
    method: 'POST',
    headers: {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      recipientId: 789,
    }),
  },
);

const result = await response.json();
// { "success": true }

Response

{
  "success": true
}

Signing Order

When an envelope uses sequential signing, recipients sign in a specific order defined by signingOrder.

Setting Signing Order

When creating recipients, assign signingOrder values to control the sequence:

const response = await fetch('https://app.documenso.com/api/v2/envelope/recipient/create-many', {
  method: 'POST',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: 'clu1abc2def3ghi4jkl',
    data: [
      {
        email: 'approver@example.com',
        name: 'Approver',
        role: 'APPROVER',
        signingOrder: 0, // Approvers typically go first
      },
      {
        email: 'first@example.com',
        name: 'First Signer',
        role: 'SIGNER',
        signingOrder: 1,
      },
      {
        email: 'second@example.com',
        name: 'Second Signer',
        role: 'SIGNER',
        signingOrder: 2,
      },
    ],
  }),
});

To enable sequential signing, set signingOrder to SEQUENTIAL in the envelope metadata when creating or updating the envelope. See the Documents API for details.

Signing Order Behavior

Recipients with lower signingOrder values sign first
Recipients with the same signingOrder can sign simultaneously
CC recipients receive the document after all signing is complete
APPROVER recipients must approve before signers with higher order values

Authentication Options

For enhanced security, you can require additional authentication when recipients access or sign a document.

Access Authentication

Controls who can view the document:

Type	Description
`ACCOUNT`	Recipient must be logged in
`TWO_FACTOR_AUTH`	Recipient must verify with 2FA

Action Authentication

Controls who can sign the document:

Type	Description
`ACCOUNT`	Recipient must be logged in
`PASSKEY`	Require passkey authentication
`TWO_FACTOR_AUTH`	Require 2FA code
`PASSWORD`	Require password verification
`EXPLICIT_NONE`	Explicitly disable action authentication

Example

const response = await fetch('https://app.documenso.com/api/v2/envelope/recipient/create-many', {
  method: 'POST',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    envelopeId: 'clu1abc2def3ghi4jkl',
    data: [
      {
        email: 'signer@example.com',
        name: 'John Doe',
        role: 'SIGNER',
        accessAuth: ['ACCOUNT'],
        actionAuth: ['PASSKEY', 'TWO_FACTOR_AUTH'],
      },
    ],
  }),
});

Error Responses

Status	Description
`400`	Invalid request body or recipient already exists
`400`	Envelope is already completed
`401`	Invalid or missing API key
`404`	Envelope or recipient not found
`500`	Server error

Example Error Response

{
  "message": "Recipient already exists"
}

Recipient Object

Recipient Roles

Get Recipient

Example

Response

Create Recipients

Request Body

Example

Response

Update Recipients

Request Body

Example

Response

Delete Recipient

Request Body

Example

Response

Signing Order

Setting Signing Order

Signing Order Behavior

Authentication Options

Access Authentication

Action Authentication

Example

Error Responses

Example Error Response

See Also

On this page