Elgato_dark/documenso
1
0
Fork 0
mirror of https://github.com/documenso/documenso synced 2026-04-21 13:27:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
documenso/apps/docs/content/docs/developers/api/recipients.mdx
Lucas Smith b92c53dbb2
feat: docs v2 (#2460) 
Co-authored-by: Catalin Pit <catalinpit@gmail.com>
2026-02-27 22:05:27 +11:00

504 lines
13 KiB
Text
Raw Blame History

---
title: Recipients API
description: Add and manage envelope recipients via API.
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Callout type="warn">
This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference,
see the [OpenAPI Reference](https://openapi.documenso.com).
</Callout>
## Recipient Object
```json
{
"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
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl "https://app.documenso.com/api/v2/envelope/recipient/789" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch(
'https://app.documenso.com/api/v2/envelope/recipient/789',
{
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
},
},
);
const recipient = await response.json();
```
</Tab>
</Tabs>
### 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
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
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
}
]
}'
````
</Tab>
<Tab value="TypeScript">
```typescript
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();
````
</Tab>
</Tabs>
### Response
```json
{
"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
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
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
}
]
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
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();
```
</Tab>
</Tabs>
### 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
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/delete" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"recipientId": 789
}'
````
</Tab>
<Tab value="TypeScript">
```typescript
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 }
````
</Tab>
</Tabs>
### Response
```json
{
"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:
```typescript
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,
},
],
}),
});
```
<Callout type="info">
To enable sequential signing, set `signingOrder` to `SEQUENTIAL` in the envelope metadata when
creating or updating the envelope. See the [Documents API](/docs/developers/api/documents) for
details.
</Callout>
### 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
```typescript
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
```json
{
"message": "Recipient already exists"
}
```
---
## See Also
- [Documents API](/docs/developers/api/documents) - Create and manage envelopes
- [Fields API](/docs/developers/api/fields) - Add signature fields for recipients
Reference in a new issue View git blame Copy permalink