diff --git a/apps/docs/content/docs/developers/api/common-errors.mdx b/apps/docs/content/docs/developers/api/common-errors.mdx index f26eba13c..91fcb9313 100644 --- a/apps/docs/content/docs/developers/api/common-errors.mdx +++ b/apps/docs/content/docs/developers/api/common-errors.mdx @@ -15,6 +15,8 @@ This guide provides a comprehensive troubleshooting matrix for the standard erro | `INVALID_REQUEST` | The overall request is malformed or invalid. | Review your API call parameters, including the URL, query parameters, and headers. Correct the request syntax. | | `RECIPIENT_EXPIRED` | The signing link or recipient access has expired. | Generate and resend a new invitation to the affected recipient. | | `LIMIT_EXCEEDED` | Your account usage quota has been exceeded. | Check your current plan limits. Upgrade your subscription or wait until your billing cycle renews. | +| `MISSING_ENV_VAR` | A required environment variable is not configured on the server (500). | Primarily affects self-hosted instances: set the environment variable named in the error message and restart. On Documenso Cloud, contact support. | +| `MISSING_SIGNATURE_FIELD` | A signer has no signature field placed on the document (400). Returned when distributing an envelope. | Add at least one signature field for every recipient with a signing role before calling `/envelope/distribute`. | | `NOT_FOUND` | The requested resource could not be found (404). | Verify the resource ID (envelope, document, webhook) passed in the URL. Ensure the resource has not been deleted. | | `NOT_IMPLEMENTED` | The requested feature is not currently supported by the server. | Consult the API documentation to verify available methods. Do not use this endpoint at this time. | | `NOT_SETUP` | The required configuration for this action is incomplete. | Access your account or integration settings and complete the necessary configuration before retrying. | @@ -37,7 +39,28 @@ The following errors occur when attempting to perform actions on an envelope tha | `ENVELOPE_DRAFT` | The action cannot be performed because the envelope is still in a draft state. | Finalize the envelope configuration and transition it to the `PENDING` (sent) state before attempting this operation. | | `ENVELOPE_COMPLETED` | The action cannot be performed because the envelope is already completed. | No further modifications (e.g., adding signers, modifying documents) can be made to an envelope once the signing process is finished. | | `ENVELOPE_REJECTED` | The action cannot be performed because the envelope was rejected by a recipient. | The signing flow is permanently halted. Create a new envelope if you wish to resubmit the document. | +| `ENVELOPE_CANCELLED` | The action cannot be performed because the envelope was cancelled (400). | Create a new envelope if you need to restart the signing process. | | `ENVELOPE_LEGACY` | The action cannot be performed because the envelope uses an obsolete format. | This envelope was created with a legacy version of the system. Recreate the envelope using the current API version to interact with it. | +| `ENVELOPE_TSP_LOCKED` | An AES/QES envelope cannot be modified after it leaves the draft state (400). | Make changes while the envelope is in `DRAFT`, or create a new envelope. | + +## CSC Signing Errors + +These errors apply to Cloud Signature Consortium (CSC) signing flows. + +| Error Code | Description | Recommended Action | +| :--- | :--- | :--- | +| `CSC_INSTANCE_MODE_MISMATCH` | The requested signature level does not match the instance's CSC mode (400). | Use the signature level supported by the instance's signing configuration. | +| `CSC_UNLICENSED` | CSC signing is not licensed for this instance (403). | Enable the CSC signing license before retrying. | +| `CSC_PROVIDER_INFO_FAILED` | The CSC provider's discovery request failed or returned unusable information (500). | Check the provider URL, availability, and OAuth configuration. | +| `CSC_PROVIDER_NO_TSA` | A timestamp authority is unavailable or unusable for CSC signing (500). | Configure `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` and verify provider timestamp access. | +| `CSC_CREDENTIAL_LIST_EMPTY` | The CSC provider returned no signing credentials for the authenticated user (400). | Enrol a signing credential with the provider, then authenticate again. | +| `CSC_CERT_INVALID` | The selected signing certificate is missing, invalid, or outside its validity period (400). | Select or renew a valid certificate, then authenticate again. | +| `CSC_ALGORITHM_REFUSED` | The signing credential uses an unsupported key or digest algorithm (400). | Select a credential that satisfies the instance's CSC algorithm policy. | +| `CSC_SAD_EXPIRED_PRE_SIGN` | The signature activation data is missing, expired, or unreadable before signing (400). | Repeat the credential authorization flow. | +| `CSC_TSP_TIMEOUT` | The trust service provider did not complete the signing request before the timeout (408). | Retry the signing request after checking provider availability. | +| `CSC_EMBED_FAILED` | The returned CSC signature could not be embedded into the envelope items (400). | Restart the signing attempt. If it fails again, contact support. | +| `CSC_BASE_DOCUMENT_MUTATED` | The document changed between signature preparation and signing (500). | Restart signing from the current envelope state. | +| `CSC_REQUEST_FAILED` | A CSC provider request failed without a more specific CSC error (500). | Check provider availability and configuration, then retry. | ## See Also diff --git a/apps/docs/content/docs/developers/api/index.mdx b/apps/docs/content/docs/developers/api/index.mdx index e8d7139eb..ac64de966 100644 --- a/apps/docs/content/docs/developers/api/index.mdx +++ b/apps/docs/content/docs/developers/api/index.mdx @@ -60,8 +60,8 @@ Authorization: api_xxxxxxxxxxxxxxxx href="/docs/developers/api/templates" /> diff --git a/apps/docs/content/docs/developers/api/recipients.mdx b/apps/docs/content/docs/developers/api/recipients.mdx index 6751a400a..bb72afb92 100644 --- a/apps/docs/content/docs/developers/api/recipients.mdx +++ b/apps/docs/content/docs/developers/api/recipients.mdx @@ -6,6 +6,8 @@ description: Add and manage envelope recipients via API. import { Callout } from 'fumadocs-ui/components/callout'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + 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). @@ -16,7 +18,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; ```json { "id": 123, - "envelopeId": "clu1abc2def3ghi4jkl", + "envelopeId": "envelope_abcdefhiklmnorst", "email": "signer@example.com", "name": "John Doe", "role": "SIGNER", @@ -134,7 +136,7 @@ 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", + "envelopeId": "envelope_abcdefhiklmnorst", "data": [ { "email": "signer@example.com", @@ -164,7 +166,7 @@ const response = await fetch( 'Content-Type': 'application/json', }, body: JSON.stringify({ - envelopeId: 'clu1abc2def3ghi4jkl', + envelopeId: 'envelope_abcdefhiklmnorst', data: [ { email: 'signer@example.com', @@ -196,7 +198,7 @@ const { data: recipients } = await response.json(); "data": [ { "id": 789, - "envelopeId": "clu1abc2def3ghi4jkl", + "envelopeId": "envelope_abcdefhiklmnorst", "email": "signer@example.com", "name": "John Doe", "role": "SIGNER", @@ -209,7 +211,7 @@ const { data: recipients } = await response.json(); }, { "id": 790, - "envelopeId": "clu1abc2def3ghi4jkl", + "envelopeId": "envelope_abcdefhiklmnorst", "email": "approver@example.com", "name": "Jane Smith", "role": "APPROVER", @@ -262,7 +264,7 @@ 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", + "envelopeId": "envelope_abcdefhiklmnorst", "data": [ { "id": 789, @@ -284,7 +286,7 @@ const response = await fetch( 'Content-Type': 'application/json', }, body: JSON.stringify({ - envelopeId: 'clu1abc2def3ghi4jkl', + envelopeId: 'envelope_abcdefhiklmnorst', data: [ { id: 789, @@ -387,7 +389,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/recipien 'Content-Type': 'application/json', }, body: JSON.stringify({ - envelopeId: 'clu1abc2def3ghi4jkl', + envelopeId: 'envelope_abcdefhiklmnorst', data: [ { email: 'approver@example.com', @@ -462,7 +464,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/recipien 'Content-Type': 'application/json', }, body: JSON.stringify({ - envelopeId: 'clu1abc2def3ghi4jkl', + envelopeId: 'envelope_abcdefhiklmnorst', data: [ { email: 'signer@example.com', diff --git a/apps/docs/content/docs/developers/api/teams.mdx b/apps/docs/content/docs/developers/api/teams.mdx index 99d708b41..814b0ff8c 100644 --- a/apps/docs/content/docs/developers/api/teams.mdx +++ b/apps/docs/content/docs/developers/api/teams.mdx @@ -1,44 +1,29 @@ --- -title: Teams API -description: Manage team resources, documents, and templates with team-scoped API tokens. +title: Team-Scoped API Access +description: Use team-scoped API tokens with document and template envelopes. --- import { Callout } from 'fumadocs-ui/components/callout'; import { Step, Steps } from 'fumadocs-ui/components/steps'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + 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). -## Team Object +## Team Context -A team object contains the following properties: + + The V2 REST API does not expose `/team/*` endpoints. Create and manage teams, members, and team + settings in the Documenso web application. This page explains how a team-scoped token applies + that team context to supported API resources. + -| Property | Type | Description | -| ----------------- | -------------- | --------------------------------------------------- | -| `id` | number | Unique team identifier | -| `name` | string | Team display name | -| `url` | string | Unique team URL slug | -| `createdAt` | string | ISO 8601 timestamp | -| `avatarImageId` | string \| null | ID of the team's avatar image | -| `organisationId` | string | ID of the parent organisation | -| `currentTeamRole` | string | Your role in the team: `ADMIN`, `MANAGER`, `MEMBER` | - -### Example Team Object - -```json -{ - "id": 123, - "name": "Engineering", - "url": "engineering", - "createdAt": "2025-01-15T10:30:00.000Z", - "avatarImageId": null, - "organisationId": "org_abc123", - "currentTeamRole": "ADMIN" -} -``` +The API resolves the team from your token. You do not pass a team ID when creating, listing, or +using envelopes. The token's team ID determines which resources the request can access. ## Team-Scoped API Tokens @@ -156,26 +141,26 @@ Retrieve all documents belonging to the team: ```bash # List all team documents -curl -X GET "https://app.documenso.com/api/v2/envelope" \ +curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT" \ -H "Authorization: api_team_xxxxxxxxxxxxxxxx" # Filter by status -curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING" \ +curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=PENDING" \ -H "Authorization: api_team_xxxxxxxxxxxxxxxx" ```` ```typescript -const response = await fetch('https://app.documenso.com/api/v2/envelope', { +const response = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT', { method: 'GET', headers: { Authorization: TEAM_API_TOKEN, }, }); -const { data, pagination } = await response.json(); -console.log(`Found ${pagination.totalItems} team documents`); +const { data, count } = await response.json(); +console.log(`Found ${count} team documents`); ```` @@ -190,10 +175,11 @@ Templates created with a team token are shared across the team. ```bash -curl -X POST "https://app.documenso.com/api/v2/template/create" \ +curl -X POST "https://app.documenso.com/api/v2/envelope/create" \ -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \ -H "Content-Type: multipart/form-data" \ -F 'payload={ + "type": "TEMPLATE", "title": "NDA Template", "recipients": [ { @@ -223,6 +209,7 @@ curl -X POST "https://app.documenso.com/api/v2/template/create" \ const form = new FormData(); const payload = { + type: 'TEMPLATE', title: 'NDA Template', recipients: [ { @@ -249,7 +236,7 @@ form.append('files', fs.createReadStream('./nda-template.pdf'), { contentType: 'application/pdf', }); -const response = await fetch('https://app.documenso.com/api/v2/template/create', { +const response = await fetch('https://app.documenso.com/api/v2/envelope/create', { method: 'POST', headers: { Authorization: TEAM_API_TOKEN, @@ -257,8 +244,8 @@ const response = await fetch('https://app.documenso.com/api/v2/template/create', body: form, }); -const template = await response.json(); -console.log('Created team template:', template.id); +const { id } = await response.json(); +console.log('Created team template envelope:', id); ```` @@ -268,14 +255,14 @@ console.log('Created team template:', template.id); ```bash -curl -X GET "https://app.documenso.com/api/v2/template" \ +curl -X GET "https://app.documenso.com/api/v2/envelope?type=TEMPLATE" \ -H "Authorization: api_team_xxxxxxxxxxxxxxxx" ```` ```typescript -const response = await fetch('https://app.documenso.com/api/v2/template', { +const response = await fetch('https://app.documenso.com/api/v2/envelope?type=TEMPLATE', { method: 'GET', headers: { Authorization: TEAM_API_TOKEN, @@ -330,19 +317,19 @@ const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN; const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN; // Get pending documents from sales team -const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=PENDING', { +const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=PENDING', { headers: { Authorization: SALES_TEAM_TOKEN }, }); const salesDocs = await salesResponse.json(); // Get completed documents from legal team -const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=COMPLETED', { +const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=COMPLETED', { headers: { Authorization: LEGAL_TEAM_TOKEN }, }); const legalDocs = await legalResponse.json(); -console.log(`Sales team: ${salesDocs.pagination.totalItems} pending`); -console.log(`Legal team: ${legalDocs.pagination.totalItems} completed`); +console.log(`Sales team: ${salesDocs.count} pending`); +console.log(`Legal team: ${legalDocs.count} completed`); ``` ## Error Responses diff --git a/apps/docs/content/docs/developers/api/templates.mdx b/apps/docs/content/docs/developers/api/templates.mdx index b3f52e146..2d3675100 100644 --- a/apps/docs/content/docs/developers/api/templates.mdx +++ b/apps/docs/content/docs/developers/api/templates.mdx @@ -13,7 +13,194 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; see the [OpenAPI Reference](https://openapi.documenso.com). -## Template Object +## Use a Template Envelope + +New integrations should create a document from a template envelope with the Envelope API. + +``` +POST /envelope/use +Content-Type: multipart/form-data +``` + +The request uses `multipart/form-data`: + +| Part | Type | Required | Description | +| --------- | ------- | -------- | ------------------------------------------------------------------ | +| `payload` | JSON | Yes | Template envelope ID, recipient details, and document settings | +| `files` | File(s) | No | Replacement PDFs referenced by entries in `customDocumentData` | + +### Payload Schema + +| Field | Type | Required | Description | +| -------------------- | ------- | -------- | ------------------------------------------------------------------------ | +| `envelopeId` | string | Yes | ID of the template envelope | +| `externalId` | string | No | Your identifier for the created document envelope | +| `recipients` | array | No | Recipient details mapped to recipients in the template | +| `distributeDocument` | boolean | No | If `true`, create the document as pending and distribute it | +| `customDocumentData` | array | No | Maps uploaded replacement PDFs to template envelope items | +| `folderId` | string | No | Folder in which to create the document | +| `prefillFields` | array | No | Field values to prefill before distribution | +| `override` | object | No | Template values to override for the created document | +| `attachments` | array | No | Link attachments to add to the document | +| `formValues` | object | No | PDF form values to apply | + +Each recipient entry accepts the following fields: + +| Field | Type | Required | Description | +| -------------- | ------- | -------- | -------------------------------------------- | +| `id` | number | Yes | Recipient ID from the template envelope | +| `email` | string | Yes | Recipient email address | +| `name` | string | No | Recipient display name | +| `signingOrder` | number | No | Recipient position in sequential signing | + +Each `customDocumentData` entry maps an uploaded file to a template item: + +| Field | Type | Required | Description | +| ---------------- | ---------------- | -------- | --------------------------------------------------------------- | +| `identifier` | string \| number | Yes | Uploaded filename or zero-based file index | +| `envelopeItemId` | string | Yes | Template envelope item whose PDF the uploaded file replaces | + +### Code Examples + + + +```bash +curl -X POST "https://app.documenso.com/api/v2/envelope/use" \ + -H "Authorization: api_xxxxxxxxxxxxxxxx" \ + -F 'payload={ + "envelopeId": "envelope_template123", + "externalId": "contract-2025-001", + "recipients": [ + { + "id": 1, + "email": "john.doe@example.com", + "name": "John Doe" + } + ], + "prefillFields": [ + { + "id": 101, + "type": "text", + "value": "Senior Software Engineer" + } + ], + "distributeDocument": false + }' +``` + + +```typescript +const form = new FormData(); + +form.append( + 'payload', + JSON.stringify({ + envelopeId: 'envelope_template123', + externalId: 'contract-2025-001', + recipients: [ + { + id: 1, + email: 'john.doe@example.com', + name: 'John Doe', + }, + ], + prefillFields: [ + { + id: 101, + type: 'text', + value: 'Senior Software Engineer', + }, + ], + distributeDocument: false, + }), +); + +const response = await fetch('https://app.documenso.com/api/v2/envelope/use', { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + }, + body: form, +}); + +const document = await response.json(); +console.log('Created document envelope:', document.id); +``` + + + +### Response + +```json +{ + "id": "envelope_document123", + "recipients": [ + { + "id": 1, + "name": "John Doe", + "email": "john.doe@example.com", + "token": "recipient_token", + "role": "SIGNER", + "signingOrder": 1, + "signingUrl": "https://app.documenso.com/sign/recipient_token" + } + ] +} +``` + +### Distribute the Created Envelope + +If you leave `distributeDocument` unset or set it to `false`, distribute the created document with +`POST /envelope/distribute`. Its response confirms delivery and includes each recipient's signing URL. + +```typescript +const distributionResponse = await fetch( + 'https://app.documenso.com/api/v2/envelope/distribute', + { + method: 'POST', + headers: { + Authorization: 'api_xxxxxxxxxxxxxxxx', + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: document.id, + }), + }, +); + +const distribution = await distributionResponse.json(); +console.log('Signing URL:', distribution.recipients[0].signingUrl); +``` + +```json +{ + "success": true, + "id": "envelope_document123", + "recipients": [ + { + "id": 1, + "name": "John Doe", + "email": "john.doe@example.com", + "token": "recipient_token", + "role": "SIGNER", + "signingOrder": 1, + "signingUrl": "https://app.documenso.com/sign/recipient_token" + } + ] +} +``` + +--- + +## Deprecated Template Endpoint Reference + + + Every `/template/*` endpoint below is deprecated. Use the Envelope API for new integrations and + follow [Migrating to Envelopes](/docs/developers/api/migrate-to-envelopes) to replace existing calls. + The legacy reference remains here to support migrations. + + +## Legacy Template Object A template object contains the following properties: @@ -91,7 +278,7 @@ A template object contains the following properties: } ``` -## List Templates +## List Templates (Deprecated) Retrieve a paginated list of templates. @@ -139,8 +326,8 @@ const response = await fetch(`${BASE_URL}/template`, { }, }); -const { data, pagination } = await response.json(); -console.log(`Found ${pagination.totalItems} templates`); +const { data, count } = await response.json(); +console.log(`Found ${count} templates`); // Filter by type const privateResponse = await fetch( @@ -181,18 +368,16 @@ const privateTemplates = await privateResponse.json(); ] } ], - "pagination": { - "page": 1, - "perPage": 10, - "totalPages": 3, - "totalItems": 25 - } + "count": 25, + "currentPage": 1, + "perPage": 10, + "totalPages": 3 } ``` --- -## Get Template +## Get Template (Deprecated) Retrieve a single template by ID. @@ -238,9 +423,9 @@ Returns the full template object including recipients, fields, and metadata. --- -## Create Document from Template +## Create Document from Template (Deprecated) -Create a new document using a template. This is the primary way to use templates programmatically. +Create a new document using the deprecated template endpoint. This endpoint does not support [PDF placeholder parsing](/docs/users/documents/advanced/pdf-placeholders). Use `POST /envelope/create` for placeholder-based field positioning. @@ -415,32 +600,57 @@ const prefilledDocument = await prefillResponse.json(); ### Response -Returns the created document object with recipients and signing URLs. +The endpoint returns the full legacy document object. The selected fields below show both the numeric +legacy `id` and canonical `envelopeId`. Recipient entries do not include a `signingUrl`. ```json { - "id": "envelope_xyz789", - "type": "DOCUMENT", + "id": 789, + "envelopeId": "envelope_xyz789", "status": "PENDING", - "title": "Employment Contract", "source": "TEMPLATE", + "title": "Employment Contract", "externalId": "contract-2025-001", "recipients": [ { "id": 1, + "envelopeId": "envelope_xyz789", + "documentId": 789, + "templateId": null, "email": "john.doe@example.com", "name": "John Doe", "role": "SIGNER", "signingStatus": "NOT_SIGNED", - "signingUrl": "https://app.documenso.com/sign/abc123" + "signingOrder": 1 } ] } -```` +``` + +To send a document created with `distributeDocument: false` and receive signing links, call +`POST /envelope/distribute` with its `envelopeId`: + +```typescript +const document = await response.json(); + +const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: document.envelopeId, + }), +}); + +const distribution = await distributionResponse.json(); +console.log('Signing URL:', distribution.recipients[0].signingUrl); +``` --- -## Override Template Settings +## Override Template Settings (Deprecated) When creating a document from a template, you can override various settings: @@ -488,7 +698,7 @@ const response = await fetch(`${BASE_URL}/template/use`, { --- -## Prefill Fields +## Prefill Fields (Deprecated) Prefill field values when creating a document from a template. This is useful for populating known data before sending. @@ -577,7 +787,7 @@ const response = await fetch(`${BASE_URL}/template/use`, { --- -## Update Template +## Update Template (Deprecated) Update a template's properties. @@ -643,7 +853,7 @@ const template = await response.json(); --- -## Duplicate Template +## Duplicate Template (Deprecated) Create a copy of an existing template. @@ -695,7 +905,7 @@ console.log('New template ID:', duplicatedTemplate.id); --- -## Delete Template +## Delete Template (Deprecated) Delete a template. @@ -754,7 +964,7 @@ const { success } = await response.json(); --- -## Direct Link Templates +## Direct Link Templates (Deprecated) Direct link templates allow recipients to create and sign documents without requiring you to explicitly create each document. When a recipient visits the direct link, a new document is automatically created from the template. @@ -898,7 +1108,7 @@ const { success } = await response.json(); --- -## Custom Document Data +## Custom Document Data (Deprecated) When creating a document from a template, you can replace the template's PDF with a custom PDF by using the `customDocumentData` parameter. This is useful when you need to generate the PDF dynamically while reusing the template's recipient and field configuration. @@ -913,7 +1123,7 @@ See the [OpenAPI Reference](https://openapi.documenso.com) for the full request --- -## Template Types +## Template Types (Legacy) | Type | Description | | --------- | ------------------------------------------------------------------ | @@ -922,7 +1132,7 @@ See the [OpenAPI Reference](https://openapi.documenso.com) for the full request --- -## Complete Example: Contract Workflow +## Complete Legacy Example: Contract Workflow (Deprecated) This example demonstrates a complete workflow for using templates to send contracts. @@ -996,16 +1206,29 @@ async function sendEmploymentContract(employeeData: { subject: `Employment Contract for ${employeeData.name}`, message: `Hi ${employeeData.name},\n\nPlease review and sign your employment contract.`, }, - distributeDocument: true, + distributeDocument: false, externalId: `emp-contract-${Date.now()}`, }), }); const document = await documentResponse.json(); + // 5. Distribute the envelope and get recipient signing links + const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + envelopeId: document.envelopeId, + }), + }); + const distribution = await distributionResponse.json(); + return { - documentId: document.id, - signingUrl: document.recipients[0].signingUrl, + envelopeId: document.envelopeId, + signingUrl: distribution.recipients[0].signingUrl, }; } @@ -1018,7 +1241,7 @@ const result = await sendEmploymentContract({ startDate: '2025-03-01', }); -console.log('Document created:', result.documentId); +console.log('Document created:', result.envelopeId); console.log('Signing URL:', result.signingUrl); ```` diff --git a/apps/docs/content/docs/developers/examples/common-workflows.mdx b/apps/docs/content/docs/developers/examples/common-workflows.mdx index 5bdf32cdf..1d6614e01 100644 --- a/apps/docs/content/docs/developers/examples/common-workflows.mdx +++ b/apps/docs/content/docs/developers/examples/common-workflows.mdx @@ -256,8 +256,11 @@ Use templates for repeatable document workflows. This example creates an employm Map template fields by label and build a prefillFields array - Call POST /template/use with recipients, prefill data, and{' '} - distributeDocument: true + Call POST /template/use with recipients and prefill data + + + Distribute the returned envelope via POST /envelope/distribute and read its signing + links @@ -291,7 +294,7 @@ type TemplateRecipient = { async function sendEmploymentContract( templateId: number, employee: EmployeeData, -): Promise<{ documentId: string; signingUrl: string }> { +): Promise<{ documentId: number; signingUrl: string }> { const templateResponse = await fetch(`${BASE_URL}/template/${templateId}`, { headers: { Authorization: API_TOKEN }, }); @@ -368,7 +371,6 @@ async function sendEmploymentContract( subject: `Your Employment Contract at ${employee.department}`, message: `Hi ${employee.name},\n\nPlease review and sign your employment contract for the ${employee.position} position.\n\nStart date: ${employee.startDate}`, }, - distributeDocument: true, externalId: `emp-${Date.now()}-${employee.email.split('@')[0]}`, }), }); @@ -380,9 +382,25 @@ async function sendEmploymentContract( const document = await createResponse.json(); + const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ envelopeId: document.envelopeId }), + }); + + if (!distributeResponse.ok) { + const error = await distributeResponse.json(); + throw new Error(`Failed to send document: ${error.message}`); + } + + const distributeResult = await distributeResponse.json(); + return { documentId: document.id, - signingUrl: document.recipients[0].signingUrl, + signingUrl: distributeResult.recipients[0].signingUrl, }; } @@ -447,12 +465,17 @@ RESPONSE=$(curl -s -X POST "${BASE_URL}/template/use" \ \"subject\": \"Your Employment Contract\", \"message\": \"Please review and sign your employment contract.\" }, - \"distributeDocument\": true, \"externalId\": \"emp-$(date +%s)-alice\" }") -echo "Document created:" -echo $RESPONSE | jq '{id, signingUrl: .recipients[0].signingUrl}' +ENVELOPE_ID=$(echo $RESPONSE | jq -r '.envelopeId') +DISTRIBUTE_RESPONSE=$(curl -s -X POST "${BASE_URL}/envelope/distribute" \ + -H "Authorization: ${API_TOKEN}" \ + -H "Content-Type: application/json" \ + -d "{\"envelopeId\": \"${ENVELOPE_ID}\"}") + +echo "Document created: $(echo $RESPONSE | jq -r '.id')" +echo "Signing URL: $(echo $DISTRIBUTE_RESPONSE | jq -r '.recipients[0].signingUrl')" ```` @@ -470,8 +493,10 @@ Send the same document to multiple recipients in parallel. Useful for policy ack Fetch the template and get the signer recipient slot ID - For each recipient, call POST /template/use with{' '} - distributeDocument: true + For each recipient, call POST /template/use + + + Distribute each returned envelope via POST /envelope/distribute Process in batches with a short delay to respect rate limits (e.g. 1000 requests/minute) @@ -534,7 +559,6 @@ async function bulkSendFromTemplate( recipients: [ { id: signerSlot.id, email: recipient.email, name: recipient.name }, ], - distributeDocument: true, externalId: `bulk-${Date.now()}-${recipient.email}`, }), }); @@ -545,10 +569,26 @@ async function bulkSendFromTemplate( } const document = await response.json(); + + const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, { + method: 'POST', + headers: { + Authorization: API_TOKEN, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ envelopeId: document.envelopeId }), + }); + + if (!distributeResponse.ok) { + const error = await distributeResponse.json(); + throw new Error(error.message || 'Failed to distribute document'); + } + + const distributeResult = await distributeResponse.json(); return { email: recipient.email, - envelopeId: document.id, - signingUrl: document.recipients[0].signingUrl, + envelopeId: document.envelopeId, + signingUrl: distributeResult.recipients[0].signingUrl, }; }), ); @@ -621,14 +661,24 @@ for RECIPIENT in "${RECIPIENTS[@]}"; do \"email\": \"${EMAIL}\", \"name\": \"${NAME}\" }], - \"distributeDocument\": true, \"externalId\": \"bulk-$(date +%s)-${EMAIL}\" }") - if echo $RESPONSE | jq -e '.id' > /dev/null 2>&1; then - echo " Success: $(echo $RESPONSE | jq -r '.id')" + if echo $RESPONSE | jq -e '.envelopeId' > /dev/null 2>&1; then + ENVELOPE_ID=$(echo $RESPONSE | jq -r '.envelopeId') + DISTRIBUTE_RESPONSE=$(curl -s -X POST "${BASE_URL}/envelope/distribute" \ + -H "Authorization: ${API_TOKEN}" \ + -H "Content-Type: application/json" \ + -d "{\"envelopeId\": \"${ENVELOPE_ID}\"}") + + if echo $DISTRIBUTE_RESPONSE | jq -e '.success' > /dev/null 2>&1; then + echo " Success: ${ENVELOPE_ID}" + echo " Signing URL: $(echo $DISTRIBUTE_RESPONSE | jq -r '.recipients[0].signingUrl')" + else + echo " Failed to distribute: $(echo $DISTRIBUTE_RESPONSE | jq -r '.message')" + fi else - echo " Failed: $(echo $RESPONSE | jq -r '.message')" + echo " Failed to create: $(echo $RESPONSE | jq -r '.message')" fi # Rate limiting delay @@ -831,13 +881,15 @@ After a document is completed, download the signed PDF with all signatures embed +The `version` query parameter accepts `original`, `pending`, or `signed`. + ```typescript const API_TOKEN = process.env.DOCUMENSO_API_TOKEN; const BASE_URL = 'https://app.documenso.com/api/v2'; -type DownloadVersion = 'signed' | 'original'; +type DownloadVersion = 'original' | 'pending' | 'signed'; async function downloadDocument( envelopeId: string, @@ -891,7 +943,7 @@ async function downloadAllCompletedDocuments(outputDir: string): Promise { { headers: { Authorization: API_TOKEN } }, ); - const { data, pagination } = await response.json(); + const { data, count, currentPage, perPage, totalPages } = await response.json(); for (const envelope of data) { try { @@ -905,8 +957,8 @@ async function downloadAllCompletedDocuments(outputDir: string): Promise { await new Promise((resolve) => setTimeout(resolve, 500)); } - hasMore = page < pagination.totalPages; - page++; + hasMore = currentPage < totalPages; + page = currentPage + 1; } } diff --git a/apps/docs/content/docs/developers/getting-started/authentication.mdx b/apps/docs/content/docs/developers/getting-started/authentication.mdx index 82d42bb1a..42d4311da 100644 --- a/apps/docs/content/docs/developers/getting-started/authentication.mdx +++ b/apps/docs/content/docs/developers/getting-started/authentication.mdx @@ -24,20 +24,18 @@ import { Step, Steps } from 'fumadocs-ui/components/steps'; {/* prettier-ignore */} -### Open settings +### Select a team -- Log in to your Documenso account -- Click your avatar in the top right corner -- Select **Settings** from the dropdown menu - -![User dropdown menu](/public-api-images/documenso-user-dropdown-menu.webp) +Log in to Documenso and open the team that the integration should access. API tokens are scoped to a +team. -### Navigate to the API Tokens tab +### Open API Tokens -Go to **Settings** and open the **API Tokens** tab. +Go to **Team Settings** → **API Tokens**, or open +`/t/{teamUrl}/settings/tokens` after replacing `{teamUrl}` with your team's URL. ![API tokens page](/public-api-images/api-tokens-page-documenso.webp) @@ -48,7 +46,7 @@ Go to **Settings** and open the **API Tokens** tab. - Click **Create Token** - Enter a descriptive name (e.g., `production-backend`, `zapier-integration`) -- Select an expiration period: never expires, 7 days, 1 month, 3 months, 6 months, or 1 year +- Select an expiration period: 7 days, 1 month, 3 months, 6 months, 12 months, or Never - Click **Create Token** @@ -75,21 +73,21 @@ Include the token in the `Authorization` header of your HTTP requests. ### cURL ```bash -curl https://app.documenso.com/api/v2/document \ +curl https://app.documenso.com/api/v2/envelope \ -H "Authorization: api_xxxxxxxxxxxxxxxx" ``` ### JavaScript / TypeScript ```typescript -const response = await fetch('https://app.documenso.com/api/v2/document', { +const response = await fetch('https://app.documenso.com/api/v2/envelope', { method: 'GET', headers: { Authorization: 'api_xxxxxxxxxxxxxxxx', }, }); -const documents = await response.json(); +const envelopes = await response.json(); ``` ### Using the TypeScript SDK @@ -129,7 +127,7 @@ SDKs are available for [TypeScript](https://github.com/documenso/sdk-typescript) ## Token Security -API tokens grant full access to your account. Follow these practices to keep them secure: +API tokens grant full API access to the team they were created for. Follow these practices to keep them secure: - **Never commit tokens to version control.** Use environment variables instead. - **Use descriptive names.** Names like `zapier-prod` or `backend-staging` help you identify token usage. @@ -155,12 +153,11 @@ const client = new Documenso({ ## Token Scope -API tokens have full access to your account, including: +API tokens have full API access to the team they were created for, including: - Creating, reading, updating, and deleting documents - Managing recipients and fields - Accessing templates -- Managing team resources (if the token owner has team access) There is currently no way to create tokens with limited scopes or permissions. @@ -171,7 +168,7 @@ To revoke a token: {/* prettier-ignore */} - Go to **Settings** > **API Tokens** + Go to **Team Settings** → **API Tokens** Find the token you want to revoke @@ -194,7 +191,7 @@ Revoked tokens stop working immediately. Any integrations using that token will Create a new token in settings. - Ensure you're accessing resources owned by the token's account. + Ensure you're accessing resources owned by the token's team.