mirror of
https://github.com/documenso/documenso.git
synced 2025-11-14 08:42:12 +10:00
chore: add envelope docs (#2186)
This commit is contained in:
David Nguyen
GitHub
@ -9,11 +9,11 @@ Documenso uses API keys for authentication. An API key is a unique token that is
|
||||
|
||||
## Creating an API Key
|
||||
|
||||
To create an API key, navigate to the user settings page. Click on your avatar in the top right corner of the dashboard and select "**[User settings](https://app.documenso.com/settings)**" from the dropdown menu.
|
||||
To create an API key, navigate to the user settings page. Click on your avatar in the top right corner of the dashboard and select "Team Settings" from the dropdown menu.
|
||||
|
||||
|
||||
|
||||
Once you're on the user settings page, navigate to the "**[API Tokens](https://app.documenso.com/settings/tokens)**" tab. The "API Token" page lists your existing keys and enables you to create new ones.
|
||||
Once you're on the settings page, navigate to the **API Tokens** tab. This page lists your existing keys and enables you to create new ones.
|
||||
|
||||
|
||||
|
||||
@ -37,31 +37,17 @@ You must include the API key in the `Authorization` request header to authentica
|
||||
Here's a sample API request using cURL:
|
||||
|
||||
```bash
|
||||
curl --location 'https://app.documenso.com/api/v1/documents?page=1&perPage=1' \
|
||||
--header 'Authorization: api_xxxxxxxxxxxxxxxx'
|
||||
curl --location 'https://app.documenso.com/api/v2/envelope/create' \
|
||||
--header 'Authorization: api_xxxxxxxxxxxxxxxx' \
|
||||
--form 'payload={ "title": "Some Title", "type": "DOCUMENT" }'
|
||||
```
|
||||
|
||||
Here's a sample response from the API based on the above cURL request:
|
||||
|
||||
```json
|
||||
{
|
||||
"documents": [
|
||||
{
|
||||
"id": 11,
|
||||
"userId": 2,
|
||||
"teamId": null,
|
||||
"title": "documenso",
|
||||
"status": "PENDING",
|
||||
"documentDataId": "ab2ecm1npk11rt5sp398waf7h",
|
||||
"createdAt": "2024-04-25T11:05:18.420Z",
|
||||
"updatedAt": "2024-04-25T11:05:36.328Z",
|
||||
"completedAt": null
|
||||
}
|
||||
],
|
||||
"totalPages": 1
|
||||
"id": "envelope_xxxxxxxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
The API key has access to your account and all its resources. Please keep it secure and do not share it with others. If you suspect your key has been compromised, you can revoke it from the "API Tokens" page in your user settings.
|
||||
The API key has access to your account and all its resources. Please keep it secure and do not share it with others. If you suspect your key has been compromised, you can revoke it from the same page you created it from.
|
||||
|
||||
@ -9,19 +9,13 @@ import { Callout, Steps } from 'nextra/components';
|
||||
|
||||
Documenso provides a public REST API enabling you to interact with your documents programmatically. The API exposes various HTTP endpoints that allow you to perform operations such as:
|
||||
|
||||
- retrieving, uploading, deleting, and sending documents for signing
|
||||
- creating, updating, and deleting recipients
|
||||
- creating, updating, and deleting document fields
|
||||
- Retrieving, uploading, deleting, and sending documents for signing
|
||||
- Creating, updating, and deleting recipients
|
||||
- Creating, updating, and deleting document fields
|
||||
|
||||
The documentation walks you through creating API keys and using them to authenticate your API requests. You'll also learn about the available endpoints, request and response formats, and how to use the API.
|
||||
|
||||
## API V1 - Stable
|
||||
|
||||
Check out the [API V1 documentation](https://app.documenso.com/api/v1/openapi) for details about the API endpoints, request parameters, response formats, and authentication methods.
|
||||
|
||||
## API V2 - Beta
|
||||
|
||||
<Callout type="warning">API V2 is currently beta, and will be subject to breaking changes</Callout>
|
||||
## API V2 - Stable
|
||||
|
||||
Check out the [API V2 documentation](https://documen.so/api-v2-docs) for details about the API endpoints, request parameters, response formats, and authentication methods.
|
||||
|
||||
@ -32,18 +26,15 @@ Our new API V2 supports the following typed SDKs:
|
||||
- [Go](https://github.com/documenso/sdk-go)
|
||||
|
||||
<Callout type="info">
|
||||
For the staging API, please use the following base URL:
|
||||
`https://stg-app.documenso.com/api/v2-beta/`
|
||||
For the staging API, please use the following base URL: `https://stg-app.documenso.com/api/v2/`
|
||||
</Callout>
|
||||
|
||||
🚀 [V2 Announcement](https://documen.so/sdk-blog)
|
||||
## API V1 - Deprecated
|
||||
|
||||
Check out the [API V1 documentation](https://app.documenso.com/api/v1/openapi) for details about the API endpoints, request parameters, response formats, and authentication methods.
|
||||
|
||||
📖 [Documentation](https://documen.so/api-v2-docs)
|
||||
|
||||
💬 [Leave Feedback](https://documen.so/sdk-feedback)
|
||||
|
||||
🔔 [Breaking Changes](https://documen.so/sdk-breaking)
|
||||
|
||||
## Availability
|
||||
|
||||
The API is available to individual users, teams and higher plans. [Fair Use](https://documen.so/fair) applies.
|
||||
|
||||
@ -7,550 +7,246 @@ import { Callout, Steps } from 'nextra/components';
|
||||
|
||||
# API Reference
|
||||
|
||||
The Swagger UI for the API is available at [/api/v1/openapi](https://app.documenso.com/api/v1/openapi). This page provides detailed information about the API endpoints, request and response formats, and authentication requirements.
|
||||
|
||||
## Upload a Document
|
||||
|
||||
Uploading a document to your Documenso account requires a two-step process.
|
||||
|
||||
<Steps>
|
||||
|
||||
### Create Document
|
||||
|
||||
First, you need to make a `POST` request to the `/api/v1/documents` endpoint, which takes a JSON payload with the following fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "string",
|
||||
"externalId": "string",
|
||||
"recipients": [
|
||||
{
|
||||
"name": "string",
|
||||
"email": "user@example.com",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 0
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"subject": "string",
|
||||
"message": "string",
|
||||
"timezone": "Etc/UTC",
|
||||
"dateFormat": "yyyy-MM-dd hh:mm a",
|
||||
"redirectUrl": "string",
|
||||
"signingOrder": "PARALLEL"
|
||||
},
|
||||
"authOptions": {
|
||||
"globalAccessAuth": "ACCOUNT",
|
||||
"globalActionAuth": "ACCOUNT"
|
||||
},
|
||||
"formValues": {
|
||||
"additionalProp1": "string",
|
||||
"additionalProp2": "string",
|
||||
"additionalProp3": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `title` _(required)_ - This represents the document's title.
|
||||
- `externalId` - This is an optional field that you can use to store an external identifier for the document. This can be useful for tracking the document in your system.
|
||||
- `recipients` _(required)_ - This is an array of recipient objects. Each recipient object has the following fields:
|
||||
- `name` - The name of the recipient.
|
||||
- `email` - The email address of the recipient.
|
||||
- `role` - The role of the recipient. See the [available roles](/users/signing-documents#roles).
|
||||
- `signingOrder` - The order in which the recipient should sign the document. This is an integer value starting from 0.
|
||||
- `meta` - This object contains additional metadata for the document. It has the following fields:
|
||||
- `subject` - The subject of the email that will be sent to the recipients.
|
||||
- `message` - The message of the email that will be sent to the recipients.
|
||||
- `timezone` - The timezone in which the document should be signed.
|
||||
- `dateFormat` - The date format that should be used in the document.
|
||||
- `redirectUrl` - The URL to which the user should be redirected after signing the document.
|
||||
- `signingOrder` - The signing order for the document. This can be either `SEQUENTIAL` or `PARALLEL`.
|
||||
- `authOptions` - This object contains authentication options for the document. It has the following fields:
|
||||
- `globalAccessAuth` - The authentication level required to access the document. This can be either `ACCOUNT` or `null`.
|
||||
- If the document is set to `ACCOUNT`, all recipients must authenticate with their Documenso account to access it.
|
||||
- The document can be accessed without a Documenso account if it's set to `null`.
|
||||
- `globalActionAuth` - The authentication level required to perform actions on the document. This can be `ACCOUNT`, `PASSKEY`, `TWO_FACTOR_AUTH`, or `null`.
|
||||
- If the document is set to `ACCOUNT`, all recipients must authenticate with their Documenso account to perform actions on the document.
|
||||
- If it's set to `PASSKEY`, all recipients must have the passkey active to perform actions on the document.
|
||||
- If it's set to `TWO_FACTOR_AUTH`, all recipients must have the two-factor authentication active to perform actions on the document.
|
||||
- If it's set to `null`, all the recipients can perform actions on the document without any authentication.
|
||||
- `formValues` - This object contains additional form values for the document. This property only works with native PDF fields and accepts three types: number, text and boolean.
|
||||
On this page we will refer to both Documents and Templates as Envelopes for convenience, unless otherwise specified.
|
||||
|
||||
<Callout type="info">
|
||||
The `globalActionAuth` property is only available for Enterprise accounts.
|
||||
This page is used to demonstrate some of the endpoints and how to use them. For the full API
|
||||
reference, please see the [API Reference](https://openapi.documenso.com/).
|
||||
</Callout>
|
||||
|
||||
Here's an example of the JSON payload for uploading a document:
|
||||
## Get Envelope
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "my-document.pdf",
|
||||
"externalId": "12345",
|
||||
"recipients": [
|
||||
{
|
||||
"name": "Alex Blake",
|
||||
"email": "alexblake@email.com",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 1
|
||||
},
|
||||
{
|
||||
"name": "Ash Drew",
|
||||
"email": "ashdrew@email.com",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 0
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"subject": "Sign the document",
|
||||
"message": "Hey there, please sign this document.",
|
||||
"timezone": "Europe/London",
|
||||
"dateFormat": "Day, Month Year",
|
||||
"redirectUrl": "https://mysite.com/welcome",
|
||||
"signingOrder": "SEQUENTIAL"
|
||||
},
|
||||
"authOptions": {
|
||||
"globalAccessAuth": "ACCOUNT",
|
||||
"globalActionAuth": "PASSKEY"
|
||||
}
|
||||
}
|
||||
For the vast majority of use cases, you will need to retrieve the envelope to get details for further operations.
|
||||
|
||||
The main details you generally want to extract are the following:
|
||||
|
||||
- **Recipients** - The individuals who will be signing the document
|
||||
- **Fields** - The fields the user will sign
|
||||
- **Items** - The PDF files the user will see and sign
|
||||
|
||||
This is done by doing a the following GET [request](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/create)
|
||||
|
||||
```sh
|
||||
curl -X GET "https://app.documenso.com/api/v2/envelope/envelope_xxxxxxxxxxxxx" \
|
||||
-H "Authorization: api_xxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
### Upload to S3
|
||||
|
||||
A successful API call to the `/api/v1/documents` endpoint returns a JSON response containing the upload URL, document ID, and recipient information.
|
||||
|
||||
The upload URL is a pre-signed S3 URL that you can use to upload the document to the Documenso (or your) S3 bucket. You need to make a `PUT` request to this URL to upload the document.
|
||||
|
||||
```json
|
||||
{
|
||||
"uploadUrl": "https://<url>/<bucket-name>/<id>/my-document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credentials>&X-Amz-Date=<date>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host&x-id=PutObject",
|
||||
"documentId": 51,
|
||||
"recipients": [
|
||||
{
|
||||
"recipientId": 11,
|
||||
"name": "Alex Blake",
|
||||
"email": "alexblake@email.com",
|
||||
"token": "<unique-signer-token>",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 1,
|
||||
"signingUrl": "https://app.documenso.com/sign/<unique-signer-token>"
|
||||
},
|
||||
{
|
||||
"recipientId": 12,
|
||||
"name": "Ash Drew",
|
||||
"email": "ashdrew@email.com",
|
||||
"token": "<unique-signer-token>",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 0,
|
||||
"signingUrl": "https://app.documenso.com/sign/<unique-signer-token>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When you make the `PUT` request to the pre-signed URL, you need to include the document file you want to upload. The image below shows how to upload a document to the S3 bucket via Postman.
|
||||
|
||||
|
||||
|
||||
Here's an example of how to upload a document using cURL:
|
||||
|
||||
```bash
|
||||
curl --location --request PUT 'https://<url>/<bucket-name>/<id>/my-document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=<credentials>&X-Amz-Date=<date>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host&x-id=PutObject' \
|
||||
--form '=@"/Users/my-user/Documents/documenso.pdf"'
|
||||
```
|
||||
|
||||
Once the document is successfully uploaded, you can access it in your Documenso account dashboard. The screenshot below shows the document that was uploaded via the API.
|
||||
|
||||
|
||||
|
||||
</Steps>
|
||||
|
||||
## Generate Document From Template
|
||||
|
||||
Documenso allows you to generate documents from templates. This is useful when you have a standard document format you want to reuse.
|
||||
|
||||
The API endpoint for generating a document from a template is `/api/v1/templates/{templateId}/generate-document`, and it takes a JSON payload with the following fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "string",
|
||||
"externalId": "string",
|
||||
"recipients": [
|
||||
{
|
||||
"id": 0,
|
||||
"name": "string",
|
||||
"email": "user@example.com",
|
||||
"signingOrder": 0
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"subject": "string",
|
||||
"message": "string",
|
||||
"timezone": "string",
|
||||
"dateFormat": "string",
|
||||
"redirectUrl": "string",
|
||||
"signingOrder": "PARALLEL"
|
||||
},
|
||||
"authOptions": {
|
||||
"globalAccessAuth": "ACCOUNT",
|
||||
"globalActionAuth": "ACCOUNT"
|
||||
},
|
||||
"formValues": {
|
||||
"additionalProp1": "string",
|
||||
"additionalProp2": "string",
|
||||
"additionalProp3": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The JSON payload is identical to the payload for uploading a document, so you can read more about the fields in the [Create Document](/developers/public-api/reference#create-document) step. For this API endpoint, the `recipients` property is required.
|
||||
|
||||
<Steps>
|
||||
|
||||
### Grab the Template ID
|
||||
|
||||
The first step is to retrieve the template ID from the Documenso dashboard. You can find the template ID in the URL by navigating to the template details page.
|
||||
|
||||
|
||||
|
||||
In this case, the template ID is "99999".
|
||||
|
||||
### Retrieve the Recipient(s) ID(s)
|
||||
|
||||
Once you have the template ID, the next step involves retrieving the ID(s) of the recipient(s) from the template. You can do this by making a GET request to `/api/v1/templates/{template-id}`.
|
||||
|
||||
A successful response looks as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 0,
|
||||
"externalId": "string",
|
||||
"type": "PUBLIC",
|
||||
"title": "string",
|
||||
"userId": 0,
|
||||
"teamId": 0,
|
||||
"templateDocumentDataId": "string",
|
||||
"createdAt": "2024-10-11T08:46:58.247Z",
|
||||
"updatedAt": "2024-10-11T08:46:58.247Z",
|
||||
"templateMeta": {
|
||||
"id": "string",
|
||||
"subject": "string",
|
||||
"message": "string",
|
||||
"timezone": "string",
|
||||
"dateFormat": "string",
|
||||
"templateId": 0,
|
||||
"redirectUrl": "string",
|
||||
"signingOrder": "PARALLEL"
|
||||
},
|
||||
"directLink": {
|
||||
"token": "string",
|
||||
"enabled": true
|
||||
},
|
||||
"templateDocumentData": {
|
||||
"id": "string",
|
||||
"type": "S3_PATH",
|
||||
"data": "string"
|
||||
},
|
||||
"Field": [
|
||||
{
|
||||
"id": 0,
|
||||
"recipientId": 0,
|
||||
"type": "SIGNATURE",
|
||||
"page": 0,
|
||||
"positionX": "string",
|
||||
"positionY": "string",
|
||||
"width": "string",
|
||||
"height": "string"
|
||||
}
|
||||
],
|
||||
"Recipient": [
|
||||
{
|
||||
"id": 0,
|
||||
"email": "user@example.com",
|
||||
"name": "string",
|
||||
"signingOrder": 0,
|
||||
"authOptions": "string",
|
||||
"role": "CC"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You'll need the recipient(s) ID(s) for the next step.
|
||||
|
||||
### Generate the Document
|
||||
|
||||
To generate a document from the template, you need to make a POST request to the `/api/v1/templates/{template-id}/generate-document` endpoint.
|
||||
|
||||
At the minimum, you must provide the `recipients` array in the JSON payload. Here's an example of the JSON payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"recipients": [
|
||||
{
|
||||
"id": 0,
|
||||
"name": "Ash Drew",
|
||||
"email": "ashdrew@email.com",
|
||||
"signingOrder": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Filling the `recipients` array with the corresponding recipient for each template placeholder recipient is recommended. For example, if the template has two placeholders, you should provide at least two recipients in the `recipients` array. Otherwise, the document will be sent to inexistent recipients such as `<recipient.1@documenso.com>`. However, the recipients can always be edited via the API or the web app.
|
||||
|
||||
A successful response will contain the document ID and recipient(s) information.
|
||||
|
||||
```json
|
||||
{
|
||||
"documentId": 999,
|
||||
"recipients": [
|
||||
{
|
||||
"recipientId": 0,
|
||||
"name": "Ash Drew",
|
||||
"email": "ashdrew@email.com",
|
||||
"token": "<signing-token>",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": null,
|
||||
"signingUrl": "https://app.documenso.com/sign/<signing-token>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can now access the document in your Documenso account dashboard. The screenshot below shows the document that was generated from the template.
|
||||
|
||||
|
||||
|
||||
</Steps>
|
||||
|
||||
## Add Fields to Document
|
||||
|
||||
The API allows you to add fields to a document via the `/api/v1/documents/{documentId}/fields` endpoint. This is useful when you want to add fields to a document before sending it to recipients.
|
||||
|
||||
To add fields to a document, you need to make a `POST` request with a JSON payload containing the field(s) information.
|
||||
|
||||
```json
|
||||
{
|
||||
"recipientId": 0,
|
||||
"type": "SIGNATURE",
|
||||
"pageNumber": 0,
|
||||
"pageX": 0,
|
||||
"pageY": 0,
|
||||
"pageWidth": 0,
|
||||
"pageHeight": 0,
|
||||
"fieldMeta": {
|
||||
"label": "string",
|
||||
"placeholder": "string",
|
||||
"required": true,
|
||||
"readOnly": true,
|
||||
"type": "text",
|
||||
"text": "string",
|
||||
"characterLimit": 0
|
||||
}
|
||||
}
|
||||
|
||||
// or
|
||||
|
||||
[
|
||||
{
|
||||
"recipientId": 0,
|
||||
"type": "SIGNATURE",
|
||||
"pageNumber": 0,
|
||||
"pageX": 0,
|
||||
"pageY": 0,
|
||||
"pageWidth": 0,
|
||||
"pageHeight": 0
|
||||
},
|
||||
{
|
||||
"recipientId": 0,
|
||||
"type": "TEXT",
|
||||
"pageNumber": 0,
|
||||
"pageX": 0,
|
||||
"pageY": 0,
|
||||
"pageWidth": 0,
|
||||
"pageHeight": 0,
|
||||
"fieldMeta": {
|
||||
"label": "string",
|
||||
"placeholder": "string",
|
||||
"required": true,
|
||||
"readOnly": true,
|
||||
"type": "text",
|
||||
"text": "string",
|
||||
"characterLimit": 0
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
<Callout type="info">This endpoint accepts either one field or an array of fields.</Callout>
|
||||
|
||||
Before adding fields to a document, you need each recipient's ID. If the document already has recipients, you can query the document to retrieve the recipient's details. If the document has no recipients, you need to add a recipient via the UI or API before adding a field.
|
||||
|
||||
<Steps>
|
||||
|
||||
### Retrieve the Recipient(s) ID(s)
|
||||
|
||||
Perform a `GET` request to the `/api/v1/documents/{id}` to retrieve the details of a specific document, including the recipient's information.
|
||||
|
||||
An example response would look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 137,
|
||||
"externalId": null,
|
||||
"userId": 3,
|
||||
"teamId": null,
|
||||
"title": "documenso.pdf",
|
||||
"internalVersion": 2,
|
||||
"type": "TEMPLATE",
|
||||
"status": "DRAFT",
|
||||
"documentDataId": "<document-data-id>",
|
||||
"createdAt": "2024-10-11T12:29:12.725Z",
|
||||
"updatedAt": "2024-10-11T12:29:12.725Z",
|
||||
"source": "TEMPLATE",
|
||||
"visibility": "EVERYONE",
|
||||
"templateType": "PRIVATE",
|
||||
"id": "envelope_xxxxxxxxxxxxxxxx",
|
||||
"secondaryId": "template_9",
|
||||
"externalId": null,
|
||||
"createdAt": "2025-11-12T11:36:38.391Z",
|
||||
"updatedAt": "2025-11-12T11:36:55.648Z",
|
||||
"completedAt": null,
|
||||
"deletedAt": null,
|
||||
"title": "Title",
|
||||
"recipients": [
|
||||
{
|
||||
"id": 55,
|
||||
"documentId": 137,
|
||||
"email": "ashdrew@email.com",
|
||||
"name": "Ash Drew",
|
||||
"envelopeId": "envelope_xxxxxxxxxxxxxxxx",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": null,
|
||||
"token": "<signing-token>",
|
||||
"signedAt": null,
|
||||
"readStatus": "NOT_OPENED",
|
||||
"signingStatus": "NOT_SIGNED",
|
||||
"sendStatus": "NOT_SENT",
|
||||
"signingUrl": "https://app.documenso.com/sign/<signing-token>"
|
||||
"id": 0,
|
||||
"email": "recipient+1@documenso.com",
|
||||
"name": "",
|
||||
"token": "cxH2Ss79Hj94M1U3PxRAG",
|
||||
"documentDeletedAt": null,
|
||||
"expired": null,
|
||||
"signedAt": null,
|
||||
"authOptions": {
|
||||
"accessAuth": [],
|
||||
"actionAuth": []
|
||||
},
|
||||
"signingOrder": 1,
|
||||
"rejectionReason": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
From this response, you'll only need the recipient ID, which is `55` in this case.
|
||||
|
||||
### (OR) Add a Recipient
|
||||
|
||||
If the document doesn't already have recipient(s), you can add recipient(s) via the API. Make a `POST` request to the `/api/v1/documents/{documentId}/recipients` endpoint with the recipient information. This endpoint takes the following JSON payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string",
|
||||
"email": "user@example.com",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 0,
|
||||
"authOptions": {
|
||||
"actionAuth": "ACCOUNT"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Callout type="info">The `authOptions` property is only available for Enterprise accounts.</Callout>
|
||||
|
||||
Here's an example of the JSON payload for adding a recipient:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Ash Drew",
|
||||
"email": "ashdrew@email.com",
|
||||
"role": "SIGNER",
|
||||
"signingOrder": 0
|
||||
}
|
||||
```
|
||||
|
||||
A successful request will return a JSON response with the newly added recipient. You can now use the recipient ID to add fields to the document.
|
||||
|
||||
### Add Field(s)
|
||||
|
||||
Now you can make a `POST` request to the `/api/v1/documents/{documentId}/fields` endpoint with the field(s) information. Here's an example:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"recipientId": 55,
|
||||
"type": "SIGNATURE",
|
||||
"pageNumber": 1,
|
||||
"pageX": 50,
|
||||
"pageY": 20,
|
||||
"pageWidth": 25,
|
||||
"pageHeight": 5
|
||||
},
|
||||
{
|
||||
"recipientId": 55,
|
||||
"type": "TEXT",
|
||||
"pageNumber": 1,
|
||||
"pageX": 20,
|
||||
"pageY": 50,
|
||||
"pageWidth": 30,
|
||||
"pageHeight": 7.5,
|
||||
"fieldMeta": {
|
||||
"label": "Address",
|
||||
"placeholder": "32 New York Street, 41241",
|
||||
"required": true,
|
||||
"readOnly": false,
|
||||
"type": "text",
|
||||
"text": "32 New York Street, 41241",
|
||||
"characterLimit": 40
|
||||
"envelopeItems": [
|
||||
{
|
||||
"envelopeId": "envelope_xxxxxxxxxxxxxxxx",
|
||||
"id": "envelope_item_xxxxxxxxxxxxxxxxx",
|
||||
"title": "FileOne",
|
||||
"order": 1
|
||||
}
|
||||
}
|
||||
]
|
||||
],
|
||||
// Other attributes
|
||||
}
|
||||
```
|
||||
|
||||
## Create Envelope
|
||||
|
||||
This example request will create a document with the following:
|
||||
|
||||
- Two PDF files
|
||||
- Two recipients with one field each
|
||||
|
||||
You will need to:
|
||||
|
||||
- Replace api_xxxxxxxxxxxxxx with your API key
|
||||
- Replace the file paths with the actual paths to your files
|
||||
|
||||
Note that the identifier on a field is linking to the files you upload. It can either be the index of the file or the filename. In this example it uses the index of the file.
|
||||
|
||||
```sh
|
||||
curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
|
||||
-H "Authorization: api_xxxxxxxxxxxxxx" \
|
||||
-H "Content-Type: multipart/form-data" \
|
||||
-F 'payload={
|
||||
"type": "DOCUMENT",
|
||||
"title": "Envelope Full Field Test",
|
||||
"recipients": [
|
||||
{
|
||||
"email": "recipient+1@example.com",
|
||||
"name": "Recipient One",
|
||||
"role": "SIGNER",
|
||||
"fields": [
|
||||
{
|
||||
"identifier": 0,
|
||||
"type": "SIGNATURE",
|
||||
"page": 1,
|
||||
"positionX": 0,
|
||||
"positionY": 0,
|
||||
"width": 50,
|
||||
"height": 50
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"email": "recipient-2@example.com",
|
||||
"name": "Recipient Two",
|
||||
"role": "SIGNER",
|
||||
"fields": [
|
||||
{
|
||||
"identifier": 1,
|
||||
"type": "SIGNATURE",
|
||||
"page": 1,
|
||||
"positionX": 0,
|
||||
"positionY": 0,
|
||||
"width": 50,
|
||||
"height": 50
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}' \
|
||||
-F "files=@./field-font-alignment.pdf;type=application/pdf" \
|
||||
-F "files=@./field-meta.pdf;type=application/pdf"
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
The `text` field represents the default value of the field. If the user doesn't provide any other
|
||||
value, this is the value that will be used to sign the field.
|
||||
See the full request and response formats for the create endpoint
|
||||
[here](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/create)
|
||||
</Callout>
|
||||
|
||||
<Callout type="warning">
|
||||
It's important to pass the `type` in the `fieldMeta` property for the advanced fields. [Read more
|
||||
here](#a-note-on-advanced-fields)
|
||||
## Use Template
|
||||
|
||||
Documenso allows you to generate documents from templates. This is useful when you have a standard document format you want to reuse.
|
||||
|
||||
The API endpoint for generating a document from a template is `/api/v2/envelopes/use`, and it takes a JSON payload with the following fields:
|
||||
|
||||
<Callout type="info">
|
||||
See the full request and response formats for the use endpoint
|
||||
[here](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/use)
|
||||
</Callout>
|
||||
|
||||
A successful request will return a JSON response with the newly added fields. The image below illustrates the fields added to the document via the API.
|
||||
<Steps>
|
||||
|
||||
|
||||
### Grab the Template ID
|
||||
|
||||
</Steps>
|
||||
The first step is to retrieve the ID of the template you want to use. This can be done via the API or from the Documenso UI.
|
||||
|
||||
#### A Note on Advanced Fields
|
||||
You can get the ID by navigating to the template page and looking at the URL. The ID is the last part of the URL which looks like this "envelope_xxxxxxxx"
|
||||
|
||||
The advanced fields are: text, checkbox, radio, number, and select. Whenever you append any of these advanced fields to a document, you need to pass the `type` in the `fieldMeta` property:
|
||||
### Retrieve the Recipient(s) ID(s)
|
||||
|
||||
```json
|
||||
...
|
||||
"fieldMeta": {
|
||||
"type": "text",
|
||||
}
|
||||
...
|
||||
Once you have the template ID, you will want to retrieve the full template so you can see the recipients.
|
||||
|
||||
This is optional, and you only will want to do this if you want to modify the recipient details prior to creating the new document.
|
||||
|
||||
See the [Get Envelope](#get-envelope) section for more details on how to retrieve the envelope.
|
||||
|
||||
### Generate the Document
|
||||
|
||||
To generate a document from the template, you need to make a POST request to the [`/api/v2/envelope/use`](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/use) endpoint.
|
||||
|
||||
You will need to replace the following:
|
||||
|
||||
- `api_xxxxxxxxxxxxxx` with your API key
|
||||
- `envelope_xxxxxxxxxxxxxxx` with the template ID
|
||||
- `RECIPIENT_ID_HERE` with the recipient ID you want to modify prior to sending
|
||||
- `RECIPIENT_EMAIL_HERE` with the new recipient email you want to use
|
||||
- `RECIPIENT_NAME_HERE` with the new recipient name you want to use
|
||||
|
||||
If you want to send the document immediately, you can add the `distributeDocument` parameter to the payload.
|
||||
|
||||
```sh
|
||||
curl -X POST "https://app.documenso.com/api/v2/envelope/use" \
|
||||
-H "Authorization: api_xxxxxxxxxxxxxx" \
|
||||
-H "Content-Type: multipart/form-data" \
|
||||
-F 'payload={
|
||||
"envelopeId": "envelope_xxxxxxxxxxxxxxx",
|
||||
"recipients": [
|
||||
{
|
||||
"id": RECIPIENT_ID_HERE,
|
||||
"email": "RECIPIENT_EMAIL_HERE",
|
||||
"name": "RECIPIENT_NAME_HERE"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Replace the `text` value with the corresponding field type:
|
||||
#### Generate the Document with Custom Files
|
||||
|
||||
- For the `TEXT` field it should be `text`.
|
||||
- For the `CHECKBOX` field it should be `checkbox`.
|
||||
- For the `RADIO` field it should be `radio`.
|
||||
- For the `NUMBER` field it should be `number`.
|
||||
- For the `SELECT` field it should be `select`. (check this before merge)
|
||||
You can also generate a document from a template using custom PDF files to replace the template's default PDF files.
|
||||
|
||||
You must pass this property at all times, even if you don't need to set any other properties. If you don't, the endpoint will throw an error.
|
||||
To do this, you will need to grab the `envelopeItemId` of the item you want to replace, this is found in the GET request in the previous step.
|
||||
|
||||
## Pre-fill Fields On Document Creation
|
||||
You will need to replace the following:
|
||||
|
||||
- `CUSTOM_FILE_NAME_HERE.pdf` with the custom file name
|
||||
- `envelope_item_xxxxxxxxxxxxxxxxx` with the `envelopeItemId` of the item you want to replace
|
||||
|
||||
```sh
|
||||
curl -X POST "https://app.documenso.com/api/v2/envelope/use" \
|
||||
-H "Authorization: api_xxxxxxxxxxxxxx" \
|
||||
-H "Content-Type: multipart/form-data" \
|
||||
-F 'payload={
|
||||
"envelopeId": "envelope_xxxxxxxxxxxxxxx",
|
||||
"recipients": [
|
||||
{
|
||||
"id": RECIPIENT_ID_HERE,
|
||||
"email": "RECIPIENT_EMAIL_HERE",
|
||||
"name": "RECIPIENT_NAME_HERE"
|
||||
}
|
||||
],
|
||||
"customDocumentData": [
|
||||
{
|
||||
"identifier": "CUSTOM_FILE_NAME_HERE.pdf",
|
||||
"envelopeItemId": "envelope_item_xxxxxxxxxxxxxxxxx"
|
||||
}
|
||||
]
|
||||
}' \
|
||||
-F "files=@./CUSTOM_FILE_NAME_HERE.pdf;type=application/pdf"
|
||||
```
|
||||
|
||||
You can now access the document in your Documenso account dashboard.
|
||||
|
||||
#### Pre-fill Fields On Document Creation
|
||||
|
||||
The API allows you to pre-fill fields on document creation. This is useful when you want to create a document from an existing template and pre-fill the fields with specific values.
|
||||
|
||||
To pre-fill a field, you need to make a `POST` request to the `/api/v1/templates/{templateId}/generate-document` endpoint with the field information. Here's an example:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "my-document.pdf",
|
||||
"recipients": [
|
||||
{
|
||||
"id": 3,
|
||||
"name": "Example User",
|
||||
"email": "example@documenso.com",
|
||||
"signingOrder": 1,
|
||||
"role": "SIGNER"
|
||||
}
|
||||
],
|
||||
"prefillFields": [
|
||||
{
|
||||
"id": 21,
|
||||
@ -574,51 +270,96 @@ To pre-fill a field, you need to make a `POST` request to the `/api/v1/templates
|
||||
"value": ["option-1", "option-2"]
|
||||
}
|
||||
]
|
||||
// Other payload properties...
|
||||
}
|
||||
```
|
||||
|
||||
Check out the endpoint in the [API V1 documentation](https://app.documenso.com/api/v1/openapi#:~:text=/%7BtemplateId%7D/-,generate,-%2Ddocument).
|
||||
</Steps>
|
||||
|
||||
### API V2
|
||||
## Add Recipients
|
||||
|
||||
For API V2, you need to make a `POST` request to the `/api/v2-beta/template/use` endpoint with the field(s) information. Here's an example:
|
||||
The API allows you to add recipients to an envelope via the [`/api/v2/envelope/recipient/create-many`](https://openapi.documenso.com/reference#tag/envelope-recipients/POST/envelope/recipient/create-many) endpoint.
|
||||
|
||||
```json
|
||||
{
|
||||
"templateId": 111,
|
||||
"recipients": [
|
||||
{
|
||||
"id": 3,
|
||||
"name": "Example User",
|
||||
"email": "example@documenso.com",
|
||||
"signingOrder": 1,
|
||||
"role": "SIGNER"
|
||||
}
|
||||
],
|
||||
"prefillFields": [
|
||||
{
|
||||
"id": 21,
|
||||
"type": "text",
|
||||
"label": "my-label",
|
||||
"placeholder": "my-placeholder",
|
||||
"value": "my-value"
|
||||
},
|
||||
{
|
||||
"id": 22,
|
||||
"type": "number",
|
||||
"label": "my-label",
|
||||
"placeholder": "my-placeholder",
|
||||
"value": "123"
|
||||
},
|
||||
{
|
||||
"id": 23,
|
||||
"type": "checkbox",
|
||||
"label": "my-label",
|
||||
"placeholder": "my-placeholder",
|
||||
"value": ["option-1", "option-2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
The following is an example of a request which creates 2 new recipients on the envelope.
|
||||
|
||||
```sh
|
||||
curl https://app.documenso.com/api/v2/envelope/recipient/create-many \
|
||||
--request POST \
|
||||
--header 'Authorization: api_xxxxxxxxxxxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"envelopeId": "envelope_brxkyaxywuxkyeuv",
|
||||
"data": [
|
||||
{
|
||||
"name": "Recipient Name",
|
||||
"email": "example@documenso.com",
|
||||
"role": "SIGNER"
|
||||
},
|
||||
{
|
||||
"name": "Recipient Two",
|
||||
"email": "example+2@documenso.com",
|
||||
"role": "APPROVER"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Check out the endpoint in the [API V2 documentation](https://openapi.documenso.com/reference#tag/template/POST/template/use).
|
||||
## Add Fields
|
||||
|
||||
The API allows you to add fields to an envelope via the [`/api/v2/envelope/field/create-many`](https://openapi.documenso.com/reference#tag/envelope-fields/POST/envelope/field/create-many) endpoint.
|
||||
|
||||
Before adding fields to an envelope, you will need the following details:
|
||||
|
||||
- **Envelope ID** - Which envelope the field will be added to
|
||||
- **Recipient ID** - Which recipient the field will be added to
|
||||
- **Envelope Item ID** - Which file the field will be added to. If blank, the field will be added to the first file.
|
||||
|
||||
See the [Get Envelope](#get-envelope) section for more details on how to retrieve these details.
|
||||
|
||||
The following is an example of a request which creates 2 new fields on the first page of the envelope.
|
||||
|
||||
Note that width, height, positionX and positionY are percentage numbers between 0 and 100, which scale the field relative to the size of the PDF.
|
||||
|
||||
```sh
|
||||
curl https://app.documenso.com/api/v2/envelope/field/create-many \
|
||||
--request POST \
|
||||
--header 'Authorization: api_xxxxxxxxxxxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"envelopeId": "envelope_xxxxxxxxxx",
|
||||
"data": [
|
||||
{
|
||||
"recipientId": recipient_id_here,
|
||||
"envelopeItemId": "envelope_item_id_here",
|
||||
"type": "TEXT",
|
||||
"page": 1,
|
||||
"positionX": 0,
|
||||
"positionY": 0,
|
||||
"width": 50,
|
||||
"height": 50,
|
||||
"fieldMeta": {
|
||||
"type": "text",
|
||||
"label": "First test field"
|
||||
}
|
||||
},
|
||||
{
|
||||
"recipientId": recipient_id_here,
|
||||
"envelopeItemId": "envelope_item_id_here",
|
||||
"type": "TEXT",
|
||||
"page": 1,
|
||||
"positionX": 50,
|
||||
"positionY": 50,
|
||||
"width": 50,
|
||||
"height": 50,
|
||||
"fieldMeta": {
|
||||
"type": "text",
|
||||
"label": "Second test field"
|
||||
}
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Field meta allows you to further configure fields, for example it will allow you to add multiple items for checkboxes or radios.
|
||||
|
||||
A successful request will return a JSON response with the newly added fields.
|
||||
|
||||
@ -9,9 +9,9 @@ import { Callout } from 'nextra/components';
|
||||
|
||||
Documenso uses API versioning to manage changes to the public API. This allows us to introduce new features, fix bugs, and make other changes without breaking existing integrations.
|
||||
|
||||
<Callout type="info">The current version of the API is `v1`.</Callout>
|
||||
<Callout type="info">The current version of the API is `v2`.</Callout>
|
||||
|
||||
The API version is specified in the URL. For example, the base URL for the `v1` API is `https://app.documenso.com/api/v1`.
|
||||
The API version is specified in the URL. For example, the base URL for the `v2` API is `https://app.documenso.com/api/v2`.
|
||||
|
||||
We may make changes to the API without incrementing the version number. We will always try to avoid breaking changes, but in some cases, it may be necessary to make changes that are not backward compatible. In these cases, we will increment the version number and provide information about the changes in the release notes.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user