Seal Docs
API Reference

Recipients API

Manage document recipients with role-based access control

Recipients API

The Recipients API allows you to manage who can view, approve, and sign documents. Recipients are assigned roles that determine their permissions and actions within the signing workflow.

The Recipient Object

Attributes

AttributeTypeDescription
idstringUnique recipient identifier
emailstringRecipient email address
namestringRecipient display name
rolestringRole: signer, approver, or viewer
statusstringStatus: pending, viewed, signed, approved, declined
ordernumberSigning order for sequential workflows (optional)
viewed_atstringISO 8601 timestamp when recipient viewed document
completed_atstringISO 8601 timestamp when recipient signed/approved
signing_urlstringDirect URL for recipient to sign (only in GET single recipient)

Example Object

{
  "id": "rec_abc123",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "signer",
  "status": "signed",
  "order": 1,
  "viewed_at": "2024-01-27T10:45:00Z",
  "completed_at": "2024-01-27T11:00:00Z"
}

Recipient Roles

RoleCan ViewCan ApproveCan SignDescription
signer✓-✓Must sign the document
approver✓✓-Must approve before signing can proceed
viewer✓--Can only view the document (no action required)

Recipient Status Flow

pending → viewed → signed/approved
            ↓
        declined
StatusDescription
pendingRecipient has not yet viewed the document
viewedRecipient has opened the document
signedSigner has completed signing
approvedApprover has approved the document
declinedRecipient has declined to sign/approve

List Recipients

Retrieve all recipients for a document.

Endpoint

GET /api/v1/recipients?document_id={documentId}

Required Scope

seal:recipients:read

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients?document_id=jd7k8l9m0n1p2q3r4s5t6u7v",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  },
);

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

cURL Example

curl -X GET "https://seal.convex.site/api/v1/recipients?document_id=jd7k8l9m0n1p2q3r4s5t6u7v" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "data": [
    {
      "id": "rec_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "signer",
      "status": "signed",
      "order": 1,
      "viewed_at": "2024-01-27T10:45:00Z",
      "completed_at": "2024-01-27T11:00:00Z"
    },
    {
      "id": "rec_def456",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "signer",
      "status": "pending",
      "order": 2
    }
  ]
}

Get Recipient

Retrieve a single recipient by ID.

Endpoint

GET /api/v1/recipients/get?document_id={documentId}&id={id}

Required Scope

seal:recipients:read

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients/get?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  },
);

const recipient = await response.json();

cURL Example

curl -X GET "https://seal.convex.site/api/v1/recipients/get?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "id": "rec_abc123",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "signer",
  "status": "pending",
  "order": 1,
  "signing_url": "https://seal.nyc/sign/abc123xyz"
}

Note: The signing_url is only included when retrieving a single recipient. This URL allows the recipient to access the document directly without authentication.

Add Recipient

Add a new recipient to a document.

Endpoint

POST /api/v1/recipients?document_id={documentId}

Required Scope

seal:recipients:write

Request Body

FieldTypeRequiredDescription
emailstringYesRecipient email address
namestringYesRecipient display name
rolestringYesRole: signer, approver, or viewer
ordernumberNoSigning order (for sequential workflows)
messagestringNoCustom message for this recipient

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients?document_id=jd7k8l9m0n1p2q3r4s5t6u7v",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "john@example.com",
      name: "John Doe",
      role: "signer",
      order: 1,
      message: "Please review and sign this agreement.",
    }),
  },
);

const recipient = await response.json();

cURL Example

curl -X POST "https://seal.convex.site/api/v1/recipients?document_id=jd7k8l9m0n1p2q3r4s5t6u7v" \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "name": "John Doe",
    "role": "signer",
    "order": 1
  }'

Response

{
  "id": "rec_abc123",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "signer",
  "status": "pending",
  "order": 1
}

Update Recipient

Update a recipient's information.

Endpoint

PUT /api/v1/recipients/update?document_id={documentId}&id={id}

Required Scope

seal:recipients:write

Request Body

FieldTypeDescription
namestringNew recipient name
emailstringNew recipient email
ordernumberNew signing order

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients/update?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "John Smith",
      order: 2,
    }),
  },
);

const recipient = await response.json();

cURL Example

curl -X PUT "https://seal.convex.site/api/v1/recipients/update?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "order": 2
  }'

Warning: You cannot change a recipient's role or email after they have viewed or signed the document. Create a new recipient instead.

Remove Recipient

Remove a recipient from a document.

Endpoint

DELETE /api/v1/recipients/delete?document_id={documentId}&id={id}

Required Scope

seal:recipients:write

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients/delete?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  },
);

const result = await response.json();
// Returns { "deleted": true } with 200 on success

cURL Example

curl -X DELETE "https://seal.convex.site/api/v1/recipients/delete?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here"

Warning: You cannot remove a recipient who has already signed or approved the document.

Send Reminder

Send a reminder email to a recipient.

Endpoint

POST /api/v1/recipients/remind?document_id={documentId}&id={id}

Required Scope

seal:recipients:write

Request Body

FieldTypeRequiredDescription
messagestringNoCustom reminder message

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/recipients/remind?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Gentle reminder to review and sign the agreement.",
    }),
  },
);

const result = await response.json();

cURL Example

curl -X POST "https://seal.convex.site/api/v1/recipients/remind?document_id=jd7k8l9m0n1p2q3r4s5t6u7v&id=rec_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Gentle reminder to review and sign."
  }'

Response

{
  "id": "rec_abc123",
  "reminder_sent": true,
  "sent_at": "2024-01-27T14:00:00Z"
}

Rate Limiting: You can only send one reminder per recipient every 24 hours to prevent spam.

Sequential Signing

Use the order field to enforce a signing sequence. Recipients with lower order numbers must complete their action before recipients with higher numbers receive the document.

Example

// Add recipients in sequence
await fetch("https://seal.convex.site/api/v1/recipients?document_id=doc123", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "ceo@example.com",
    name: "CEO",
    role: "approver",
    order: 1, // Must approve first
  }),
});

await fetch("https://seal.convex.site/api/v1/recipients?document_id=doc123", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "employee@example.com",
    name: "Employee",
    role: "signer",
    order: 2, // Can only sign after CEO approves
  }),
});

Next Steps

Last updated on

Documents API

Complete API reference for document management endpoints

Templates API

Create and manage reusable document templates with custom fields

On this page

Recipients APIThe Recipient ObjectAttributesExample ObjectRecipient RolesRecipient Status FlowList RecipientsEndpointRequired ScopeTypeScript ExamplecURL ExampleResponseGet RecipientEndpointRequired ScopeTypeScript ExamplecURL ExampleResponseAdd RecipientEndpointRequired ScopeRequest BodyTypeScript ExamplecURL ExampleResponseUpdate RecipientEndpointRequired ScopeRequest BodyTypeScript ExamplecURL ExampleRemove RecipientEndpointRequired ScopeTypeScript ExamplecURL ExampleSend ReminderEndpointRequired ScopeRequest BodyTypeScript ExamplecURL ExampleResponseSequential SigningExampleNext Steps