Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: v2.1
title: Docusign eSignature REST Document Generation API
description: The Docusign eSignature REST API provides you with a powerful, convenient, and simple Web services API for interacting with Docusign.
termsOfService: https://www.docusign.com/company/terms-and-conditions/web
contact:
name: Docusign Developer Center
url: https://developers.docusign.com/
email: devcenter@docusign.com
servers:
- url: https://www.docusign.net/restapi
tags:
- name: DocumentGeneration
description: '[Document generation][webapp support page] enables you
to create reusable templates
with professionally formatted documents
that include personalized data.
For example, you can create
a boilerplate employment offer letter
that is updated with job details
for each candidate from an HR system .
To learn more about using these endpoints
with the eSignature API,
see [Document generation][concepts page]
in the eSignature concepts guide.
[webapp support page]: https://support.docusign.com/s/document-item?bundleId=als1679428547895&topicId=ldx1679428689631.html
[concepts page]: /docs/esign-rest-api/esign101/concepts/documents/document-generation/'
paths:
/v2.1/accounts/{accountId}/envelopes/{envelopeId}/docGenFormFields:
parameters: []
get:
tags:
- DocumentGeneration
summary: Returns sender fields for an envelope
operationId: DocGenFormFields_GetEnvelopeDocGenFormFields
parameters:
- name: accountId
in: path
description: The external account number (int) or account ID GUID.
required: true
schema:
type: string
- name: envelopeId
in: path
description: "The envelope's GUID. \n\nExample: `93be49ab-xxxx-xxxx-xxxx-f752070d71ec`\n"
required: true
schema:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/docGenFormFieldResponse'
'400':
description: Error encountered.
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: getEnvelopeDocGenFormFields
x-ds-method: getEnvelopeDocGenFormFields
x-ds-service: Uncategorized
description: 'Given an `envelopeId`, this method returns the sender fields found in that envelope''s documents. After you retrieve the sender fields, use the DocumentGeneration::updateEnvelopeDocGenFormFields method to populate the fields.
If the specified envelope does not contain a document with sender fields, the method will return success (`200`) and an empty object (`{}`) in the response.
### Next steps
- Learn about document generation in the eSignature concepts guide.
- Learn how to send an envelope with document generation in your preferred coding language.'
x-ds-in-sdk: true
put:
tags:
- DocumentGeneration
summary: Updates sender fields for an envelope
operationId: DocGenFormFields_PutEnvelopeDocGenFormFields
parameters:
- name: accountId
in: path
description: The external account number (int) or account ID GUID.
required: true
schema:
type: string
- name: envelopeId
in: path
description: "The envelope's GUID. \n\nExample: `93be49ab-xxxx-xxxx-xxxx-f752070d71ec`\n"
required: true
schema:
type: string
- name: update_docgen_formfields_only
in: query
required: false
description: 'When **false** or omitted,
the documents are updated.
When **true,** only the form fields are updated. The documents are unchanged.
'
schema:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/docGenFormFieldResponse'
'400':
description: Error encountered.
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: updateEnvelopeDocGenFormFields
x-ds-method: updateEnvelopeDocGenFormFields
x-ds-service: Uncategorized
description: 'This method dynamically generates an envelope''s documents by populating its sender fields. The envelope must be in a draft state.
Use the DocumentGeneration::getEnvelopeDocGenFormFields response to retrieve the list of sender fields for your envelope. Use that list to build the request for this method. For each field, specify the field name and the value to populate.
For example, your request body might look like this:
```json
{
"docGenFormFields": [
{
"documentId": "bf3202e1-xxxx-xxxx-xxxx-af4f41366879",
"docGenFormFieldList": [
{
"name": "Candidate_Name",
"value": "Peggy Olson"
},
{
"name": "Job_Title",
"value": "Technical Writer"
},
{
"name": "Manager_Name",
"value": "Donald Draper"
},
{
"name": "Start_Date",
"value": "1960-02-28"
},
{
"name": "Salary",
"value": "3380"
}
]
}
]
}
```
### Important notes
* If `update_docgen_formfields_only` is false (the default), the `documentId` changes after the update.
* This endpoint does not validate number, date, or select data field values. The request can succeed even if a number or date field value is not a valid number or date, or if a select field value is not one of the allowed values.
### Related topics
- Learn about document generation in the eSignature concepts guide.
- See this method in use in your preferred coding language.'
x-ds-in-sdk: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/docGenFormFieldRequest'
application/xml:
schema:
$ref: '#/components/schemas/docGenFormFieldRequest'
components:
schemas:
docGenFormFieldValidation:
type: object
properties:
errorMessage:
description: The error message when validation fails.
type: string
expression:
description: The expression used to validate values.
type: string
x-ds-definition-name: docGenFormFieldValidation
description: Describes how values are validated.
x-ms-summary: Describes how values are validated.
docGenFormFieldResponse:
type: object
properties:
docGenFormFields:
description: A list of `docGenFormFields` objects.
type: array
items:
$ref: '#/components/schemas/docGenFormFields'
errorDetails:
$ref: '#/components/schemas/errorDetails'
description: This object describes errors that occur. It is only valid for responses and ignored in requests.
x-ds-definition-name: docGenFormFieldResponse
description: An object for document generation responses.
x-ms-summary: An object for document generation responses.
docGenFormField:
type: object
properties:
connectedObjectDetails:
$ref: '#/components/schemas/connectedObjectDetails'
description: ''
defaultValue:
description: ''
type: string
description:
description: A description of the field. Displayed with the label.
type: string
filter:
description: An object used to present a filtered view of the items in a folder.
type: string
format:
$ref: '#/components/schemas/docGenFormat'
description: ''
fullyQualifiedPath:
description: ''
type: string
hidden:
description: ''
type: string
label:
description: A label displayed near the field.
type: string
name:
description: 'The name of the sender field.
Required for PUT requests.
'
type: string
options:
description: When `type` is `Select`, this array describes the available options.
type: array
items:
$ref: '#/components/schemas/docGenFormFieldOption'
order:
description: "The order in which to sort the results.\n\nValid values are: \n\n\n* `asc`: Ascending order.\n* `desc`: Descending order. "
type: string
predefinedValidation:
description: Reserved for Docusign.
type: string
readOnly:
description: ''
type: string
required:
description: When **true,** the field is required.
type: string
rowValues:
description: 'For fields of type `TableRow`, this property represents the sender fields in the row.
For GET requests, this array contains a single `docGenFormFieldRowValue` object. That object contains a list of sender fields that will appear in each row.
For PUT requests, you must supply a `docGenFormFieldRowValue` object for each row in the table. This populates the data in the table.
'
type: array
items:
$ref: '#/components/schemas/docGenFormFieldRowValue'
type:
description: 'The kind of data the sender field holds. Valid values:
- `TextBox`
- `Date`
- `Number`
- `Select`
- `TableRow`
'
type: string
validation:
$ref: '#/components/schemas/docGenFormFieldValidation'
description: Describes how values are validated.
value:
description: 'The value of the sender field.
For PUT requests, you must supply either this property (for all fields except `TableRow` types) or `rowValues` (for `TableRow` fields).'
type: string
x-ds-definition-name: docGenFormField
description: 'The document fields available for document generation.
This object is used in reponses (GET) and requests (PUT). When used with [DocumentGeneration: updateEnvelopeDocGenFormFields](/docs/esign-rest-api/reference/envelopes/documentgeneration/updateenvelopedocgenformfields/) (PUT), the `name` and `value` / `rowValues` properties are required and any other values are ignored.
'
x-ms-summary: 'The document fields available for document generation.
This object is used in reponses (GET) and requests (PUT). When used with [DocumentGeneration: updateEnvelopeDocGenFormFields](/docs/esign-rest-api/reference/envelopes/documentgeneration/updateenvelopedocgenformfields/) (PUT), the `name` and `value` / `rowValues` properties are required and any other values are ignored.
'
docGenSyntaxError:
type: object
properties:
errorCode:
description: A code associated with the error condition.
type: string
message:
description: The error message.
type: string
tagIdentifier:
description: 'The tag that caused the syntax error.
See [Document Generation Syntax](https://support.docusign.com/s/document-item?bundleId=als1679428547895&topicId=ftc1679700030026.html)
to learn more about document generation syntax rules.'
type: string
x-ds-definition-name: docGenSyntaxError
description: Describes document generation errors.
x-ms-summary: Describes document generation errors.
docGenFormFieldOption:
type: object
properties:
description:
description: Description of the selectable option.
type: string
label:
description: The label for the selectable option.
type: string
selected:
description: When **true,** the option is selected.
type: string
value:
description: Specifies the value of the option. This is the value of the form field when this option is selected.
type: string
x-ds-definition-name: docGenFormFieldOption
description: Specifies an individual option setting when type is `Select`.
x-ms-summary: Specifies an individual option setting when type is `Select`.
connectedObjectDetails:
type: object
properties:
recordId:
description: ''
type: string
x-ds-definition-name: connectedObjectDetails
description: ''
x-ms-summary: ''
docGenFormat:
type: object
properties:
expression:
description: ''
type: string
locale:
description: 'The user''s locale code. Valid values are:
- `zh_CN`
- `zh_TW`
- `nl`
- `en`
- `fr`
- `de`
- `it`
- `ja`
- `ko`
- `pt`
- `pt_BR`
- `ru`
- `es`'
type: string
x-ds-definition-name: docGenFormat
description: ''
x-ms-summary: ''
errorDetails:
description: This object describes errors that occur. It is only valid for responses and ignored in requests.
type: object
properties:
errorCode:
description: The code associated with the error condition.
type: string
message:
description: A brief message describing the error condition.
type: string
x-ds-definition-name: errorDetails
x-ms-summary: This object describes errors that occur. It is only valid for responses and ignored in requests.
docGenFormFieldRequest:
type: object
properties:
docGenFormFields:
description: A list of `docGenFormFields` objects.
type: array
items:
$ref: '#/components/schemas/docGenFormFields'
x-ds-definition-name: docGenFormFieldRequest
description: This object maps the document generation fields to their values.
x-ms-summary: This object maps the document generation fields to their values.
docGenFormFields:
type: object
properties:
docGenDocumentStatus:
description: 'The status of the document. This is a read-only property, and not used in [updateEnvelopeDocGenFormFields][docgen update].
Valid values:
- `mergesucceeded`
- `created`
- `hassyntaxerror`
[docgen update]: /docs/esign-rest-api/reference/envelopes/documentgeneration/updateenvelopedocgenformfields/
'
type: string
docGenErrors:
description: A list of `docGenSyntaxError` objects.
type: array
items:
$ref: '#/components/schemas/docGenSyntaxError'
docGenFormFieldList:
description: A list of `docGenFormField` objects.
type: array
items:
$ref: '#/components/schemas/docGenFormField'
documentId:
description: The GUID of the document.
type: string
x-ds-definition-name: docGenFormFields
description: A collection of document generation fields.
x-ms-summary: A collection of document generation fields.
docGenFormFieldRowValue:
type: object
properties:
docGenFormFieldList:
description: 'The sender fields in each row of the table.
For GET requests, the `label`, `type`, `required`, and `name` properties will be returned.
For POST requests, supply the `name` and `value` for each child object. These correspond to the values in each column.'
type: array
items:
$ref: '#/components/schemas/docGenFormField'
x-ds-definition-name: docGenFormFieldRowValue
description: An object representing a row of a dynamic table.
x-ms-summary: An object representing a row of a dynamic table.
externalDocs:
description: See the Docusign eSignature REST API Guide for more information.
url: https://docs.docusign.com/esign
x-ds-allow-editing: false
x-ds-categories:
- name: Envelopes
summary: This section shows you how to create and send envelopes.
description: 'The eSignature API Envelope category includes the resources and methods for sending and managing envelopes and envelope data.
Envelopes are the key objects in the Docusign platform. As a result, they are complex data structures with few required fields. See the [How-to guides](/docs/esign-rest-api/how-to/) for examples and solutions.
To learn more about envelopes, see [Envelopes](/docs/esign-rest-api/esign101/concepts/envelopes/).
'
- name: Connect
summary: "Docusign Connect is the Docusign platform notification service. The service uses webhooks to proactively notify your application when an event occurs that your application wants to know about. Docusign recommends that all applications use Connect instead of polling the Docusign Signature Service. This section provides information about Connect configuration and logging. \n\n**Note:** To make API calls to any of the Connect endpoints, you must be an account administrator.\n\nFor more information about Connect, see [Docusign Connect](/platform/webhooks/connect/) and [Custom Connect Configuration](https://support.docusign.com/s/document-item?bundleId=pik1583277475390&topicId=khw1583277390582.html)."
description: 'The Connect service enables your application to be called via
HTTPS when an event of interest occurs.
Use the Connect service to "end the polling madness." With
Connect, there is no need for your application to poll Docusign
every 15 minutes to learn the latest about your envelopes.
Instead, you register your interest in one or more types of
envelope or recipient events. Then, when an interesting event
occurs, the Docusign platform will contact your application with
the event''s details and data. You can register interest in
envelopes sent by particular users in your account, or for
envelopes sent by any user.
Connect can empower your organization to manage document actions
as they occur, and allows you to track their changes within your
own systems. Upon completion, envelope information, including
document content, can be stored in your own databases or CMS
systems, and these events can be triggered via webhooks
delivering messages to your application.
**Note:** To make API calls to any of the Connect endpoints, you must be an account administrator.
## Incoming Connect Calls
To use the Connect service, your application needs to provide an
HTTPS URL that can be called from the public Internet. If your
application runs on a server behind your organization''s firewall,
then you will need to create a "pinhole" in the firewall to allow
the incoming Connect calls from Docusign to reach your
application. You can also use other techniques such as proxy
servers and DMZ networking for receiving the incoming calls.
Connect delivers events over HTTP requests in JSON or XML.
See [Docusign Connect overview](/platform/webhooks/connect/).
If your application is not configured to accept post messages,
Docusign will NOT return an additional post error response to
your listener application. If you''ve enabled logging on your
configuration, it will be logged in Admin under the configuration
failure log.
## Per-envelope Connect Configuration
Instead of registering a general Connect configuration and
listener, an individual envelope can have its own Connect
configuration. See the
[`eventNotification`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#schema__envelopedefinition_eventnotification)
property for envelopes.
## Historical Publish Endpoint
To submit existing envelopes to an endpoint, use the [EnvelopePublish](/docs/esign-rest-api/reference/envelopes/envelopepublish/) resource.
'
- name: Templates
summary: Template creation and management
description: 'Use the Templates category to manage your account''s templates.
This section shows you how to perform the following tasks:
* Create, list, get, update, and delete templates.
* Manage the notification and group sharing settings for templates.
* Fetch and rotate pages from a document used by a template.
You can create templates either programmatically or through the Docusign web interface and then used by your application.'
- name: SigningGroups
summary: Send a signing request to a group of potential signers.
description: 'Use the Signing Group category to manage signing groups that allow anyone in the group to sign a document. When you send an envelope to a signing group, anyone in the group can open it and sign it with their own signature.
This category shows account administrators how to create a signing group and manage the users in the group.
**Note:** To create and manage signing groups, you must be an account administrator.
For more information about this topic, see [Signing Groups](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).'
- name: Folders
summary: Folders allow you to organize envelopes and templates.
description: 'Use the Folders category to organize envelopes and templates.
You can list the folder contents and move envelopes and templates between folders.'
- name: CustomTabs
summary: Custom tabs
description: "Custom Tabs enable accounts to have one or more pre-configured (custom) tabs. Custom tabs save time when users are tagging documents since the users don't have to manually set the tabs' parameters.\n\nThis category enables custom tabs to be managed programmatically, including creation, deletion, etc. \n"
- name: CloudStorage
summary: This section shows you how to manage your cloud storage providers and users.
description: 'Use the Cloud Storage category to list the user''s cloud storage document contents.
It is also used to manage the user''s authentication/accounts with cloud storage service providers.'
- name: Users
summary: User management
description: 'Use the Users category to manage the users in your accounts.
You can:
* Set custom user settings.
* Manage a users profile.
* Add delete users.
* Add and delete the initials and signature images for a user.'
- name: UserGroups
summary: Group users for common permissions and branding
description: 'Use the User Groups category to manage your permissions groups.
You can:
* Create and delete groups.
* Add users to, and delete users from, your groups.
* Manage the brand information associated with a group.'
- name: BulkEnvelopes
summary: Bulk envelopes
description: Use the BulkEnvelopes category to manage the sending of envelopes to multiple recipients.
- name: Accounts
summary: Account management
description: 'Use the Account category for various account management tasks including:
* Programmatically creating and deleting accounts.
* Getting information about an account and its capabilities.
* Branding the account with custom colors, message text, and more.
* Account charges.
The Accounts category also includes end points for listing the recipient names associated with an email address that was used by the account. For example, a single email address is often shared by multiple members of a family.
'
- name: Billing
summary: Invoices
description: 'Use the Billing category to manage the following billing related tasks:
* Retrieve and update billing plan information.
* Retrieve invoices.
* Retrieve and update payment information.'
- name: Diagnostics
summary: Diagnostics and request logging
description: 'The Diagnostics category provides miscellaneous end points.
They include:
* Requesting and managing the API call-logging feature. (Perfect for debugging your app!)
* Getting information on the API''s resources and versions.'
- name: PowerForms
summary: The PowerForms category provides methods that enable you to create and manage fillable forms.
description: The PowerForms category enables you to create and manage PowerForms that you can use for self service and email forms.
- name: Workspaces
summary: A Docusign workspace is a collaboration area for sharing files and data.
description: "A workspace is a collaborative space for sharing documents and managing workflows. A workspace has a single owner who must be a Docusign user. The owner can invite others to the workspace as collaborators. Individuals who are not Docusign users must create a Docusign account to join a workspace as a collaborator.\n \nYou can create an envelope directly from a workspace.\n\nWorkspaces store the following information:\n\n- **Files:** Files uploaded to a workspace for storage or reuse.\n- **Documents:** A document is a component of a transaction, template, or workspace. When a file is added to a transaction, template, or workspace, it is copied as a document. Each document in a workspace has a single owner.\n- **Templates:** A set of documents that you can use to create a transaction or a workspace.\n- **Transactions:** A transaction is a series of workflow events related to one or more documents. These events route the documents to one or more individuals for the purposes of doing business. Each transaction has a single owner (the sender).\n\n**Note:** Documents in a template are not individually listed as files."
- name: Payments
summary: Manage Payments
description: This category includes resources for managing payment gateways. Payment information is added to envelopes via methods in the Envelopes category.
- name: EmailArchive
summary: This section shows you how to set and manage the BCC email addresses that you want to use to archive the emails that Docusign sends.
description: 'Email archives enable Docusign partners and other multi-account customers to easily archive emails sent through Docusign. The `EmailArchive` resource provides methods for managing your email archive configuration, which consists of the BCC email address or addresses that you want to use to archive Docusign emails. Each account can use up to five BCC email addresses for archiving purposes.
For more information, see [Email Archive Configuration](https://support.docusign.com/s/document-item?bundleId=pik1583277475390&topicId=xjm1583277371373.html).
**Note:** This feature is only available for certain account plans and must be enabled by Docusign.'
- name: Notary
summary: 'Docusign eNotary makes the notarization process fully digital
for senders, signers, and notaries.
It enables a notary public to act as an in-person witness
to electronic signing of documents.
'
description: 'Docusign eNotary makes the notarization process fully digital
for senders, signers, and notaries.
It enables a notary public to act as an in-person witness
to electronic signing of documents.
'
- name: Envelope
summary: ''
description: ''