DocuSign: Esignature schemas (part 9)
22 DocuSign schemas with complete fields and constraints.
← Esignature operations · All schemas
Add envelope archive metadata — request body — body event Notification
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Use this object to configure a [Docusign Connect webhook](/platform/webhooks/connect/). |
deliveryMode | string | Optional | |
envelopeEvents | array | Optional | A list of envelope-level event statuses that will trigger Connect to send updates to the endpoint specified in the `url` property. To receive notifications, you must include either an `envelopeEvents` node or a `recipientEvents` node. You do not need to specify both. |
envelopeEvents[] | Model | Each item | Expand Add envelope archive metadata — request body — body event Notification envelope Events item |
eventData | Model | Optional | Expand Add envelope archive metadata — request body — body event Notification event Data |
events | array | Optional | A comma-separated list of envelope-level event statuses that will trigger Connect to send updates to the endpoint specified in the `urlToPublishTo` property. Set this property when you are using the [JSON SIM event model](/platform/webhooks/connect/json-sim-event-model/). If you are instead using any of [the legacy event message formats](/platform/webhooks/connect/legacy-message-formats/), set either the `envelopeEvents` property or the `recipientEvents` property. The [possible event statuses](/platform/webhooks/connect/json-sim-event-reference/) are: - `envelope-created` - `envelope-sent` - `envelope-resent` - `envelope-delivered` - `envelope-completed` - `envelope-declined` - `envelope-voided` - `recipient-authenticationfailed` - `recipient-autoresponded` - `recipient-declined` - `recipient-delivered` - `recipient-completed` - `recipient-sent` - `recipient-resent` - `template-created` - `template-modified` - `template-deleted` - `envelope-corrected` - `envelope-purge` - `envelope-deleted` - `envelope-discard` - `recipient-reassign` - `recipient-delegate` - `recipient-finish-later` - `click-agreed` - `click-declined` |
events[] | string | Each item | |
includeCertificateOfCompletion | string | Optional | When **true,** the Connect Service includes the Certificate of Completion with completed envelopes. |
includeCertificateWithSoap | string | Optional | When **true,** the Connect service will digitally sign the data. The signature will be included in the message. |
includeDocumentFields | string | Optional | When **true,** the Document Fields associated with the envelope's documents are included in the notification messages. Document Fields are optional custom name-value pairs added to documents using the API. |
includeDocuments | string | Optional | When **true,** the Connect webhook messages will include the envelope's PDF documents. Including the PDF documents greatly increases the size of the notification messages. Ensure that your listener can handle incoming messages that are 25MB or larger. |
includeEnvelopeVoidReason | string | Optional | When **true,** this tells the Connect Service to include the void reason, as entered by the person that voided the envelope, in the message. |
includeHMAC | string | Optional | When **true,** HMAC headers will be included with the webhook notifications. **Note:** [HMAC must enabled](/platform/webhooks/connect/hmac/) at the account level with [one or more HMAC secrets](/platform/webhooks/connect/setting-up-hmac/). |
includeOAuth | string | Optional | |
includeSenderAccountAsCustomField | string | Optional | When **true,** Connect will include the sender account as Custom Field in the data. |
includeTimeZone | string | Optional | When **true,** the envelope's time zone information is included in the webhook messages. |
integratorManaged | string | Optional | When **true**, enables partners and integrators use their HMAC keys for their clients’ event messages. If enabled, Connect will use the partner’s or integrator’s HMAC key's while sending event notifications. You can use this parameter for account-level and envelope-level configurations. While enabled, this setting this will cause the **x-docusign-accountid** value to match the partner or integrator’s account ID. When **false**, or when not set, the **x-docusign-accountid** returns the Account ID of the user who created the envelope. |
loggingEnabled | string | Optional | When **true,** the webhook messages are logged. They can be viewed on the Docusign Administration Web Tool in the Connect section. Logged messages can also be downloaded via the [ConnectEvents resource](/docs/esign-rest-api/reference/connect/connectevents/). |
recipientEvents | array | Optional | A list of recipient event statuses that will trigger Connect to send updates to the endpoint specified in the url property. To receive notifications, you must include either an `envelopeEvents` node or a `recipientEvents` node. You do not need to specify both. |
recipientEvents[] | Model | Each item | Expand Add envelope archive metadata — request body — body event Notification recipient Events item |
requireAcknowledgment | string | Optional | When **true,** the Docusign Connect service checks that the message was received and retries on failures. |
signMessageWithX509Cert | string | Optional | When **true,** Mutual TLS will be enabled for notifications. Mutual TLS must be initiated by the listener (the customer's web server) during the TLS handshake protocol. |
soapNameSpace | string | Optional | The namespace of the SOAP interface. The namespace value must be set if useSoapInterface is set to true. |
url | string | Optional | The endpoint to which Connect should send webhook notification messages via an HTTPS POST request. The URL must start with `https`. The customer's web server must use an SSL/TLS certificate whose CA is in the Microsoft list of trusted CAs. Self-signed certificates are not acceptable, but you can use free certificates from Let's Encrypt. The maximum length of this property is 4096 bytes. |
useSoapInterface | string | Optional | When **true,** this tells the Connect service that the user's endpoint has implemented a SOAP interface. |
Referenced models: Add envelope archive metadata — request body — body event Notification event Data, Add envelope archive metadata — request body — body event Notification envelope Events item, Add envelope archive metadata — request body — body event Notification recipient Events item
Add envelope archive metadata — request body — body event Notification envelope Events item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | For which envelope events should your webhook be called? |
envelopeEventStatusCode | string | Optional | An envelope status for which your webhook should be called. Valid values: - `Sent` - `Delivered` - `Completed` - `Declined` - `Voided` |
includeDocuments | string | Optional | When **true,** the Connect webhook messages will include the envelope's PDF documents. Including the PDF documents greatly increases the size of the notification messages. Ensure that your listener can handle incoming messages that are 25MB or larger. |
Add envelope archive metadata — request body — body event Notification event Data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | This object lets you choose the data format of your Connect response. |
format | string | Optional | Reserved for Docusign. |
includeData | array | Optional | A string array of the data to be included. The default is the empty array `[]`. - `attachments`: Include attachments associated with the envelope. - `custom_fields`: Include the custom fields associated with the envelope. - `documents`: Include the documents associated with the envelope. - `extensions`: Include information about the email settings associated with the envelope. - `folders`: Include the folder where the envelope exists. - `payment_tabs`: Include the payment tabs associated with the envelope. - `powerform`: Include the PowerForms associated with the envelope. - `prefill_tabs`: Include the [pre-filled tabs](/docs/esign-rest-api/esign101/concepts/tabs/prefilled-tabs/) associated with the envelope. - `recipients`: Include the recipients associated with the envelope. - `tabs`: Include the tabs associated with the envelope. |
includeData[] | string | Each item | |
version | string | Optional | Set this property to `restv2.1` to return event data in JSON. If the property is not set, the event data will be returned in XML by default. |
Add envelope archive metadata — request body — body event Notification recipient Events item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
includeDocuments | string | Optional | When **true,** the Connect webhook messages will include the envelope's PDF documents. Including the PDF documents greatly increases the size of the notification messages. Ensure that your listener can handle incoming messages that are 25MB or larger. |
recipientEventStatusCode | string | Optional | Send a webhook notification for the following recipient statuses: Sent, Delivered, Completed, Declined, AuthenticationFailed, and AutoResponded. |
Add envelope archive metadata — request body — body folders item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | This object contains details about a folder. |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
filter | Model | Optional | Expand Add envelope archive metadata — request body — body folders item filter |
folderId | string | Optional | The ID of the folder. |
folderItems | array | Optional | A list of envelopes and templates that the folder contains. |
folderItems[] | Model | Each item | Expand Add envelope archive metadata — request body — body folders item folder Items item |
folders | array | Optional | A collection of folder objects returned in a response. |
folders[] | Model | Each item | Expand Add envelope archive metadata — request body — body folders item |
hasAccess | string | Optional | When **true,** the current user has access to the folder. |
hasSubFolders | string | Optional | When **true,** the folder has subfolders. |
itemCount | string | Optional | The number of items in the folder. |
name | string | Optional | The name of the folder. |
owner | Model | Optional | Expand Add envelope archive metadata — request body — body sender |
parentFolderId | string | Optional | The ID of the parent folder, or the special value `root` for the root folder. |
parentFolderUri | string | Optional | The URI of the parent folder. |
subFolderCount | string | Optional | The number of subfolders. |
type | string | Optional | The type of folder. Possible values include: - `draft` - `inbox` - `normal` (a system-generated folder) - `recyclebin` - `sentitems` - `custom` (a custom folder created by a user) |
uri | string | Optional | The URI for the folder. |
Referenced models: Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body folders item filter, Add envelope archive metadata — request body — body folders item, Add envelope archive metadata — request body — body folders item folder Items item, Add envelope archive metadata — request body — body sender
Add envelope archive metadata — request body — body folders item filter
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Use this object to create a filtered view of the items in a folder. |
actionRequired | string | Optional | When **true,** the current user needs to take action on the item. |
expires | string | Optional | The number of days a sent envelope remains active before it expires. |
folderIds | string | Optional | Filters for any combination of folder IDs and folder types. The possible folder types are: - `awaiting_my_signature` - `completed` - `draft` - `drafts` - `expiring_soon` - `inbox` - `out_for_signature` - `recyclebin` - `sentitems` - `waiting_for_others` |
fromDateTime | string | Optional | The UTC DateTime of the beginning of a date range. If no value is provided, the default search is the previous 30 days. |
isTemplate | string | Optional | When **true,** the item is a template. |
order | string | Optional | The order in which to sort the results. Valid values are: - `asc`: Ascending order. - `desc`: Descending order. |
orderBy | string | Optional | The field used to sort the results. Example: `Created` |
searchTarget | string | Optional | Reserved for Docusign. |
searchText | string | Optional | A free text search field for searching across the items in a folder. The search looks for the text that you enter in the recipient names and emails, envelope custom fields, sender name, and subject. |
status | string | Optional | The status of the envelope. By default, all statuses are returned. For details, see [Envelope Status Code Descriptions](/docs/esign-rest-api/esign101/rules-and-limits/responses/). |
toDateTime | string | Optional | The UTC DateTime of the end of a date range. If no value is provided, the default search is to the current date. |
Add envelope archive metadata — request body — body folders item folder Items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Information about folder item results. |
completedDateTime | string | Optional | If the item is an envelope, this is the UTC DateTime when the envelope was completed. |
createdDateTime | string | Optional | The UTC DateTime when the item was created. |
envelopeId | string | Optional | If the item is an envelope, this is the ID of the envelope. |
envelopeUri | string | Optional | If the item is an envelope, this is the URI for retrieving it. |
expireDateTime | string | Optional | The date and time the envelope is set to expire. |
folderId | string | Optional | The ID of the folder. |
folderUri | string | Optional | If the item is a subfolder, this is the URI for retrieving it. |
is21CFRPart11 | string | Optional | When **true,** indicates compliance with United States Food and Drug Administration (FDA) regulations on electronic records and electronic signatures (ERES). |
lastModifiedDateTime | string | Optional | The date and time that the item was last modified. |
ownerName | string | Optional | The name of the user who owns the folder. |
recipients | Model | Optional | Expand Add envelope archive metadata — request body — body recipients |
recipientsUri | string | Optional | Contains a URI for an endpoint that you can use to retrieve the recipients. |
senderCompany | string | Optional | The name of the sender's company. |
senderEmail | string | Optional | The sender's email address. |
senderName | string | Optional | The sender's name. |
senderUserId | string | Optional | The sender's id. |
sentDateTime | string | Optional | The UTC DateTime when the envelope was sent. This property is read-only. |
status | string | Optional | Indicates the envelope status. Valid values are: * sent - The envelope is sent to the recipients. * created - The envelope is saved as a draft and can be modified and sent later. |
subject | string | Optional | The subject of the envelope. |
templateId | string | Optional | The unique identifier of the template. If this is not provided, DocuSign will generate a value. |
templateUri | string | Optional | The URI for retrieving the template. |
Referenced models: Add envelope archive metadata — request body — body recipients
Add envelope archive metadata — request body — body generate Properties item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
applyAnchorTabs | string | Optional | |
archiveDocumentType | string | Optional | |
assignTabsToRecipientId | string | Optional | |
authoritativeCopy | string | Optional | Specifies the Authoritative copy feature. If set to true the Authoritative copy feature is enabled. |
base64DataJson | string | Optional | |
base64GenerateTemplateDocument | string | Optional | |
dataJson | string | Optional | |
display | string | Optional | |
docGenDocumentStatus | string | Optional | |
docGenFormFields | array | Optional | |
docGenFormFields[] | Model | Each item | Expand Add envelope archive metadata — request body — body documents item doc Gen Form Fields item |
documentBase64 | string | Optional | |
documentFields | array | Optional | |
documentFields[] | Model | Each item | Expand Add envelope archive metadata — request body — body envelope Custom Metadata envelope Custom Metadata Details item |
documentId | string | Optional | Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute. |
documentName | string | Optional | |
documentSequence | string | Optional | |
documentTemplateId | string | Optional | |
encryptedWithKeyManager | string | Optional | |
fileExtension | string | Optional | |
fileFormatHint | string | Optional | |
generateDocumentTemplateKind | string | Optional | |
generateDocumentTemplateSource | string | Optional | |
generateTemplateDocumentId | string | Optional | |
htmlDefinition | Model | Optional | Expand Add envelope archive metadata — request body — body documents item html Definition |
includeInDownload | string | Optional | |
isDocGenDocument | string | Optional | |
matchBoxes | array | Optional | |
matchBoxes[] | Model | Each item | Expand Add envelope archive metadata — request body — body documents item match Boxes item |
name | string | Optional | |
order | string | Optional | |
pages | string | Optional | |
password | string | Optional | |
pdfFormFieldOption | string | Optional | |
remoteUrl | string | Optional | |
signerMustAcknowledge | string | Optional | |
signerMustAcknowledgeUseAccountDefault | boolean | Optional | |
tabs | Model | Optional | Expand Add envelope archive metadata — request body — body documents item tabs |
templateLocked | string | Optional | When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. |
templateRequired | string | Optional | When set to **true**, the sender may not remove the recipient. Used only when working with template recipients. |
transformPdfFields | string | Optional | |
uri | string | Optional |
Referenced models: Add envelope archive metadata — request body — body documents item doc Gen Form Fields item, Add envelope archive metadata — request body — body documents item html Definition, Add envelope archive metadata — request body — body documents item match Boxes item, Add envelope archive metadata — request body — body envelope Custom Metadata envelope Custom Metadata Details item, Add envelope archive metadata — request body — body documents item tabs
Add envelope archive metadata — request body — body lock Information
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
lockDurationInSeconds | string | Optional | The number of seconds to lock the envelope for editing. This value must be greater than `0` seconds. |
lockToken | string | Optional | A unique identifier provided to the owner of the lock. You must use this token with subsequent calls to prove ownership of the lock. |
lockType | string | Optional | The type of lock. Currently `edit` is the only supported type. |
lockedByApp | string | Optional | The human-readable name of the application that is locking the envelope or template. This value displays to the user in error messages when lock conflicts occur. |
lockedByUser | Model | Optional | Expand Add envelope archive metadata — request body — body sender |
lockedUntilDateTime | string | Optional | The date and time that the lock expires. |
useScratchPad | string | Optional | When **true,** a scratchpad is used to edit information. |
Referenced models: Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body sender
Add envelope archive metadata — request body — body notification
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex element that specifies the notification settings for the envelope. |
expirations | Model | Optional | Expand Add envelope archive metadata — request body — body notification expirations |
reminders | Model | Optional | Expand Add envelope archive metadata — request body — body notification reminders |
useAccountDefaults | string | Optional | When **true,** the account default notification settings are used for the envelope, overriding the reminders and expirations settings. When **false,** the reminders and expirations settings specified in this request are used. The default value is **false.** |
Referenced models: Add envelope archive metadata — request body — body notification expirations, Add envelope archive metadata — request body — body notification reminders
Add envelope archive metadata — request body — body notification expirations
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex element that specifies the expiration settings for the envelope. When an envelope expires, it is voided and no longer available for signing. **Note:** there is a short delay between when the envelope expires and when it is voided. |
expireAfter | string | Optional | An integer that sets the number of days the envelope is active. For this value to be used, `expireEnabled` must be explicitly set to **true.** |
expireEnabled | string | Optional | When **true,** the envelope expires in the number of days set by `expireAfter`. When **false** or not set, the envelope expires in the number of days specified by the [default expiration account setting](https://support.docusign.com/s/document-item?bundleId=pik1583277475390&topicId=rra1583277381176.html). If you have not modified these settings, envelopes will expire after 120 days by default. |
expireWarn | string | Optional | An integer that specifying the number of days before the envelope expires that an expiration warning email is sent to the recipient. When 0 (zero), no warning email is sent. |
Add envelope archive metadata — request body — body notification reminders
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex element that specifies reminder settings for the envelope |
maximumReminderCount | string | Optional | |
reminderDelay | string | Optional | An integer specifying the number of days after the recipient receives the envelope that reminder emails are sent to the recipient. The default value is 0. |
reminderEnabled | string | Optional | When **true,** reminders are enabled. The default value is **false.** |
reminderFrequency | string | Optional | An integer specifying the interval in days between reminder emails. The default value is 0. |
smartReminderEnabled | string | Optional |
Add envelope archive metadata — request body — body power Form
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains details about a PowerForm. |
createdBy | string | Optional | The ID of the user who created the PowerForm. |
createdDateTime | string | Optional | The UTC DateTime when the item was created. |
emailBody | string | Optional | The body of the email message sent to the recipients. Maximum length: 10000 characters. |
emailSubject | string | Optional | The subject line of the email message that is sent to all recipients. For information about adding merge field information to the email subject, see [Template Email Subject Merge Fields](/docs/esign-rest-api/reference/templates/templates/create/#template-email-subject-merge-fields). **Note:** The subject line is limited to 100 characters, including any merged fields.It is not truncated. It is an error if the text is longer than 100 characters. |
envelopes | array | Optional | |
envelopes[] | Model | Each item | Expand Add envelope archive metadata — request body — body power Form envelopes item |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
instructions | string | Optional | The instructions that display on the landing page for the first recipient. These instructions are important if the recipient accesses the PowerForm by a method other than email. If instructions are entered, they display as an introduction after the recipient accesses the PowerForm. Limit: 2000 characters. |
isActive | string | Optional | When **true,** indicates that the PowerForm is active and can be sent to recipients. This is the default value. When **false,** the PowerForm cannot be emailed or accessed by a recipient, even if they arrive at the PowerForm URL. If a recipient attempts to sign an inactive PowerForm, an error message informs the recipient that the document is not active and suggests that they contact the sender. |
lastUsed | string | Optional | The UTC DateTime when the PowerForm was last used. |
limitUseInterval | string | Optional | The length of time before the same recipient can sign the same PowerForm. This property is used in combination with the `limitUseIntervalUnits` property. |
limitUseIntervalEnabled | string | Optional | When **true,** the `limitUseInterval` is enabled. |
limitUseIntervalUnits | string | Optional | The units associated with the `limitUseInterval`. Valid values are: - `minutes` - `hours - `days` - `weeks` - `months` For example, to limit a recipient to signing once per year, set the `limitUseInterval` to 365 and the `limitUseIntervalUnits` to `days`. |
maxUseEnabled | string | Optional | When **true,** you can set a maximum number of uses for the PowerForm. |
name | string | Optional | The name of the PowerForm. |
powerFormId | string | Optional | The ID of the PowerForm. |
powerFormUrl | string | Optional | The URL for the PowerForm. |
recipients | array | Optional | An array of recipient objects that provides details about the recipients of the envelope. |
recipients[] | Model | Each item | Expand Add envelope archive metadata — request body — body power Form recipients item |
senderName | string | Optional | The sender's name. |
senderUserId | string | Optional | The ID of the sender. |
signingMode | string | Optional | The signing mode to use. Valid values are: - `email`: Verifies the recipient's identity using email authentication before the recipient can sign a document. The recipient enters their email address and then clicks **Begin Signing** to begin the signing process. The system then sends an email message with a validation code for the PowerForm to the recipient. If the recipient does not provide a valid email address, they cannot open and sign the document. - `direct`: Does not require any verification. After a recipient enters their email address and clicks **Begin Signing,** a new browser tab opens and the recipient can immediately begin the signing process. Because the recipient's identity is not verified by using email authentication, we strongly recommend that you only use the `direct` signing mode when the PowerForm is accessible behind a secure portal where the recipient's identity is already authenticated, or where another form of authentication is specified for the recipient in the Docusign template (for example, an access code, phone authentication, or ID check). **Note:** In the account settings, `enablePowerFormDirect` must be **true** to use `direct` as the `signingMode`. |
templateId | string | Optional | The ID of the template used to create the PowerForm. |
templateName | string | Optional | The name of the template used to create the PowerForm. |
timesUsed | string | Optional | The number of times the PowerForm has been used. |
uri | string | Optional | The URI for the PowerForm. |
usesRemaining | string | Optional | The number of times the PowerForm can still be used. |
Referenced models: Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body power Form envelopes item, Add envelope archive metadata — request body — body power Form recipients item
Add envelope archive metadata — request body — body power Form envelopes item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accessControlListBase64 | string | Optional | Reserved for Docusign. |
allowComments | string | Optional | When **true,** users can add comments to the documents in the envelope. For example, if a signer has a question about the text in the document, they can add a comment to the document. |
allowMarkup | string | Optional | When **true,** the Document Markup feature is enabled. **Note:** To use this feature, Document Markup must be enabled at both the account and envelope levels. Only Admin users can change this setting at the account level. |
allowReassign | string | Optional | When **true,** the recipient can redirect an envelope to a more appropriate recipient. |
allowViewHistory | string | Optional | When **true,** recipients can view the history of the envelope. |
anySigner | string | Optional | Deprecated. This feature has been replaced by signing groups. |
asynchronous | string | Optional | When **true,** the envelope is queued for processing and the value of the `status` property is set to `Processing`. Additionally, GET status calls return `Processing` until completed. **Note:** A `transactionId` is required for this call to work correctly. When the envelope is created, the status is `Processing` and an `envelopeId` is not returned in the response. To get the `envelopeId`, use a GET envelope query by using the [transactionId](/docs/esign-rest-api/reference/envelopes/envelopes/create/) or by checking the Connect notification. |
attachmentsUri | string | Optional | Contains a URL for retrieving the attachments that are associated with the envelope. |
authoritativeCopy | string | Optional | When **true,** marks all of the documents in the envelope as authoritative copies. **Note:** You can override this value for a specific document. For example, you can set the `authoritativeCopy` property to **true** at the envelope level, but turn it off for a single document by setting the `authoritativeCopy` property for the document to **false.** |
authoritativeCopyDefault | string | Optional | The default `authoritativeCopy` setting for documents in this envelope that do not have `authoritativeCopy` set. If this property is not set, each document defaults to the envelope's `authoritativeCopy`. |
autoNavigation | string | Optional | When **true,** autonavigation is set for the recipient. |
brandId | string | Optional | The ID of the brand. |
brandLock | string | Optional | When **true,** the `brandId` for the envelope is locked and senders cannot change the brand used for the envelope. |
burnDefaultTabData | string | Optional | |
certificateUri | string | Optional | The URI for retrieving certificate information. |
completedDateTime | string | Optional | Specifies the date and time this item was completed. |
copyRecipientData | string | Optional | |
createdDateTime | string | Optional | The UTC DateTime when the item was created. |
customFields | Model | Optional | Expand Add envelope archive metadata — request body — body custom Fields |
customFieldsUri | string | Optional | The URI for retrieving custom fields. |
declinedDateTime | string | Optional | The date and time the recipient declined the document. This property is read-only. |
deletedDateTime | string | Optional | Reserved for Docusign. |
deliveredDateTime | string | Optional | The date and time that the envelope was delivered to the recipient. This property is read-only. |
disableResponsiveDocument | string | Optional | When **true,** responsive documents are disabled for the envelope. |
documentBase64 | string | Optional | Reserved for Docusign. |
documentsCombinedUri | string | Optional | The URI for retrieving all of the documents associated with the envelope as a single PDF file. |
documentsUri | string | Optional | The URI for retrieving all of the documents associated with the envelope as separate files. |
emailBlurb | string | Optional | This is the same as the email body. If specified it is included in email body for all envelope recipients. |
emailSettings | Model | Optional | Expand Add envelope archive metadata — request body — body email Settings |
emailSubject | string | Optional | The subject line of the email message that is sent to all recipients. For information about adding merge field information to the email subject, see [Template Email Subject Merge Fields](/docs/esign-rest-api/reference/templates/templates/create/#template-email-subject-merge-fields). **Note:** The subject line is limited to 100 characters, including any merged fields.It is not truncated. It is an error if the text is longer than 100 characters. |
enableWetSign | string | Optional | When **true,** the signer is allowed to print the document and sign it on paper. |
enforceSignerVisibility | string | Optional | When **true,** the option selected in the **Document Visibility** section in your account [Sending Settings](https://admindemo.docusign.com/authenticate?goTo=sending) will be enforced for the envelope. See [Fields and Properties](https://support.docusign.com/s/document-item?rsc_301&bundleId=pik1583277475390&topicId=xgg1583277350154.html) for details about document visibility options. Setting `enforceSignerVisibility` to **true** also enables you to omit documents from the specified recipients' envelopes by using the [`excludedDocuments`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#schema__envelopedefinition_recipients_signers_excludeddocuments) array. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all of the documents in an envelope, unless they are specifically excluded by using the `excludedDocuments` setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are excluded by using the `excludedDocuments` setting. **Note:** To use this functionality, [document visibility](/docs/esign-rest-api/reference/envelopes/envelopedocumentvisibility/) must be enabled for the account. The document visibility feature is available in all developer accounts, but only in certain production account plans. Contact [Docusign Support](https://support.docusign.com/en/contactSupport#) or your account manager to find out whether document visibility is available for your production account plan. |
envelopeAttachments | array | Optional | An array of attachment objects that provide information about the attachments that are associated with the envelope. |
envelopeAttachments[] | Model | Each item | Expand Add envelope archive metadata — request body — body attachments item |
envelopeClassification | string | Optional | |
envelopeCustomMetadata | Model | Optional | Expand Add envelope archive metadata — request body — body envelope Custom Metadata |
envelopeDocuments | array | Optional | An array containing information about the documents that are included in the envelope. |
envelopeDocuments[] | Model | Each item | Expand Add envelope archive metadata — request body — body envelope Documents item |
envelopeId | string | Optional | The envelope ID of the envelope status that failed to post. |
envelopeIdStamping | string | Optional | When **true,** [Envelope ID Stamping](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=tfm1578456367923.html) is enabled. After a document or attachment is stamped with an Envelope ID, the ID is seen by all recipients and becomes a permanent part of the document and cannot be removed. |
envelopeLocation | string | Optional | Reserved for Docusign. |
envelopeMetadata | Model | Optional | Expand Add envelope archive metadata — request body — body envelope Metadata |
envelopeUri | string | Optional | The URI for retrieving the envelope or envelopes. |
expireAfter | string | Optional | Not used. Use the [`expirations`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#definition__envelopedefinition_notification_expirations) property in the [`notification`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#definition__envelopedefinition_notification) object instead. |
expireDateTime | string | Optional | The date and time that the envelope is set to expire. This value is determined by the `InitialSentDateTime` of the envelope and the `expireAfter` property of the `notification` object. (Note that the `expireAfter` property of the envelope itself is not used.) |
expireEnabled | string | Optional | Not used. Use the [`expirations`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#definition__envelopedefinition_notification_expirations) property in the [`notification`](/docs/esign-rest-api/reference/envelopes/envelopes/create/#definition__envelopedefinition_notification) object instead. |
externalEnvelopeId | string | Optional | May contain an external identifier for the envelope. |
folders | array | Optional | A list of folder objects. |
folders[] | Model | Each item | Expand Add envelope archive metadata — request body — body folders item |
hasComments | string | Optional | When **true,** indicates that users have added comments to the envelope. |
hasFormDataChanged | string | Optional | When **true,** indicates that the data collected through form fields on a document has changed. |
hasWavFile | string | Optional | When **true,** indicates that a .wav file used for voice authentication is included in the envelope. |
holder | string | Optional | Reserved for Docusign. |
initialSentDateTime | string | Optional | The date and time the envelope was initially sent. |
is21CFRPart11 | string | Optional | When **true,** indicates compliance with United States Food and Drug Administration (FDA) regulations on electronic records and electronic signatures (ERES). |
isDynamicEnvelope | string | Optional | When **true,** indicates that the envelope is a dynamic envelope. |
isSignatureProviderEnvelope | string | Optional | When **true,** indicates that the envelope is a signature-provided envelope. |
isTicketRelatedEnvelope | string | Optional | |
lastModifiedDateTime | string | Optional | The date and time that the item was last modified. |
location | string | Optional | Reserved for Docusign. |
lockInformation | Model | Optional | Expand Add envelope archive metadata — request body — body lock Information |
messageLock | string | Optional | When **true,** prevents senders from changing the contents of `emailBlurb` and `emailSubject` properties for the envelope. Additionally, this prevents users from making changes to the contents of `emailBlurb` and `emailSubject` properties when correcting envelopes. However, if the `messageLock` node is set to **true** and the `emailSubject` property is empty, senders and correctors are able to add a subject to the envelope. |
notification | Model | Optional | Expand Add envelope archive metadata — request body — body notification |
notificationUri | string | Optional | The URI for retrieving notifications. |
powerForm | Model | Optional | Expand Add envelope archive metadata — request body — body power Form |
purgeCompletedDate | string | Optional | The date that a purge was completed. |
purgeRequestDate | string | Optional | The date that a purge was requested. |
purgeState | string | Optional | Shows the current purge state for the envelope. Valid values: - `unpurged`: There has been no successful request to purge documents. - `documents_queued`: The envelope documents have been added to the purge queue, but have not been purged. - `documents_dequeued`: The envelope documents have been taken out of the purge queue. - `documents_purged`: The envelope documents have been successfully purged. - `documents_and_metadata_queued`: The envelope documents and metadata have been added to the purge queue, but have not yet been purged. - `documents_and_metadata_purged`: The envelope documents and metadata have been successfully purged. - `documents_and_metadata_and_redact_queued`: The envelope documents and metadata have been added to the purge queue, but have not yet been purged, nor has personal information been redacted. - `documents_and_metadata_and_redact_purged`: The envelope documents and metadata have been successfully purged, and personal information has been redacted. **Related topics** - [Purging documents (eSingature Concepts)](/docs/esign-rest-api/esign101/concepts/documents/purging/) - [Purging documents in an envelope (blog post)](https://www.docusign.com/blog/developers/purging-documents-envelope) |
recipients | Model | Optional | Expand Add envelope archive metadata — request body — body recipients |
recipientsLock | string | Optional | When **true,** prevents senders from changing, correcting, or deleting the recipient information for the envelope. |
recipientsUri | string | Optional | Contains a URI for an endpoint that you can use to retrieve the recipients. |
sender | Model | Optional | Expand Add envelope archive metadata — request body — body sender |
sentDateTime | string | Optional | The UTC DateTime when the envelope was sent. This property is read-only. |
signerCanSignOnMobile | string | Optional | When **true,** recipients can sign on a mobile device. **Note:** Only Admin users can change this setting. |
signingLocation | string | Optional | Specifies the physical location where the signing takes place. It can have two enumeration values; InPerson and Online. The default value is Online. |
status | string | Optional | Indicates the envelope status. See [Envelope status code descriptions](/docs/esign-rest-api/esign101/concepts/envelopes/status-codes/#envelope-status-code-descriptions) for a list of valid values. |
statusChangedDateTime | string | Optional | The date and time when the status last changed. |
templatesUri | string | Optional | The URI for retrieving the templates. |
transactionId | string | Optional | Used to identify an envelope. The id is a sender-generated value and is valid in the DocuSign system for 7 days. It is recommended that a transaction ID is used for offline signing to ensure that an envelope is not sent multiple times. The `transactionId` property can be used determine an envelope's status (i.e. was it created or not) in cases where the internet connection was lost before the envelope status was returned. |
uSigState | string | Optional | A property that is only used internally by Docusign. |
useDisclosure | string | Optional | When **true,** the disclosure is shown to recipients in accordance with the account's Electronic Record and Signature Disclosure frequency setting. When **false,** the Electronic Record and Signature Disclosure is not shown to any envelope recipients. If the `useDisclosure` property is not set, then the account's normal disclosure setting is used and the value of the `useDisclosure` property is not returned in responses when getting envelope information. |
voidedDateTime | string | Optional | The date and time the envelope or template was voided. |
voidedReason | string | Optional | The reason the envelope or template was voided. **Note:** The string is truncated to the first 200 characters. |
watermarkLanguage | string | Optional | |
workflow | Model | Optional | Expand Add envelope archive metadata — request body — body workflow |
Referenced models: Add envelope archive metadata — request body — body attachments item, Add envelope archive metadata — request body — body custom Fields, Add envelope archive metadata — request body — body email Settings, Add envelope archive metadata — request body — body envelope Custom Metadata, Add envelope archive metadata — request body — body envelope Documents item, Add envelope archive metadata — request body — body envelope Metadata, Add envelope archive metadata — request body — body notification, Add envelope archive metadata — request body — body folders item, Add envelope archive metadata — request body — body lock Information, Add envelope archive metadata — request body — body power Form, Add envelope archive metadata — request body — body recipients, Add envelope archive metadata — request body — body sender, Add envelope archive metadata — request body — body workflow
Add envelope archive metadata — request body — body power Form recipients item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | **Note:** For a self-service PowerForm on a website, you can specify the intended recipients generically (for example, use `Member` as the `Name`), and omit personal details such as `email`. |
accessCode | string | Optional | (Optional) The access code that the recipient must enter to access the PowerForm. Maximum Length: 50 characters. The code must also conform to the account's access code format setting. If blank but the signer accessCode property is set in the envelope, then that value is used. If blank and the signer accessCode property is not set, then the access code is not required. |
accessCodeLocked | string | Optional | When **true,** the `accessCode` property is locked and cannot be edited. |
accessCodeRequired | string | Optional | When **true,** the recipient must enter the `accessCode` to access the PowerForm. |
email | string | Optional | The email address of the recipient. **Note:** For self-service documents where you do not know who the recipients are in advance, you can leave this property blank. |
emailLocked | string | Optional | When **true,** the recipient's email address is locked and cannot be edited. |
idCheckConfigurationName | string | Optional | The name of the authentication check to use. This value must match one of the authentication types that the account uses. The names of these authentication types appear in the web console sending interface in the Identify list for a recipient. This setting overrides any default authentication setting. Valid values are: - `Phone Auth $`: The recipient must authenticate by using two-factor authentication (2FA). You provide the phone number to use for 2FA in the `phoneAuthentication` object. - `SMS Auth $`: The recipient must authenticate via SMS. You provide the phone number to use in the `smsAuthentication` object. - `ID Check $`: The recipient must answer detailed security questions. **Example:** Your account has ID Check and SMS Authentication available. In the web console Identify list, these appear as ID Check $ and SMS Auth $. To use ID Check in an envelope, the idCheckConfigurationName should be ID Check $. For SMS, you would use SMS Auth $, and you would also need to add a phone number to the smsAuthentication node. |
idCheckRequired | string | Optional | Indicates if authentication is configured for the account. Valid values are: - `always`: Authentication checks are performed on every envelope. - `never`: Authentication checks are not performed on any envelopes. - `optional:` Authentication is configurable per envelope. |
name | string | Optional | The name of the PowerForm recipient. **Note:** For self-service documents where you do not know who the recipients are in advance, you can leave this property blank. |
recipientType | string | Optional | The recipient type, as specified by the following values: - `agent`: Agent recipients can add name and email information for recipients that appear after the agent in routing order. - `carbonCopy`: Carbon copy recipients get a copy of the envelope but don't need to sign, initial, date, or add information to any of the documents. This type of recipient can be used in any routing order. - `certifiedDelivery`: Certified delivery recipients must receive the completed documents for the envelope to be completed. They don't need to sign, initial, date, or add information to any of the documents. - `editor`: Editors have the same management and access rights for the envelope as the sender. Editors can add name and email information, add or change the routing order, set authentication options, and can edit signature/initial tabs and data fields for the remaining recipients. - `inPersonSigner`: In-person recipients are Docusign users who act as signing hosts in the same physical location as the signer. - `intermediaries`: Intermediary recipients can optionally add name and email information for recipients at the same or subsequent level in the routing order. - `seal`: Electronic seal recipients represent legal entities. - `signer`: Signers are recipients who must sign, initial, date, or add data to form fields on the documents in the envelope. - `witness`: Witnesses are recipients whose signatures affirm that the identified signers have signed the documents in the envelope. |
roleName | string | Optional | The role associated with the recipient (for example, `Member`). This property is required when you are working with template recipients and PowerForm recipients. |
routingOrder | string | Optional | Specifies the routing order of the recipient in the envelope. |
templateRequiresIdLookup | string | Optional | When **true,** the template used to create the PowerForm requires ID lookup for the recipient. |
userNameLocked | string | Optional | When **true,** the `userName` property for the recipient is locked and cannot be edited. |
Add envelope archive metadata — request body — body recipient View Request
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The request body for the [EnvelopeViews: createRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient/) and [EnvelopeViews: createSharedRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createsharedrecipient/) methods. |
assertionId | string | Optional | A unique identifier of the authentication event executed by the client application. |
authenticationInstant | string | Optional | A sender-generated value that indicates the date and time that the signer was authenticated. |
authenticationMethod | string | Optional | Required. Choose a value that most closely matches the technique your application used to authenticate the recipient / signer. Choose a value from this list: - Biometric - HTTPBasicAuth - Kerberos - KnowledgeBasedAuth - None - PaperDocuments - Password - RSASecureID - SingleSignOn_CASiteminder - SingleSignOn_InfoCard - SingleSignOn_MicrosoftActiveDirectory - SingleSignOn_Other - SingleSignOn_Passport - SingleSignOn_SAML - Smartcard - SSLMutualAuth - X509Certificate This information is included in the Certificate of Completion. |
clientURLs | Model | Optional | Expand Add envelope archive metadata — request body — body recipient View Request client UR Ls |
clientUserId | string | Optional | A sender-created value. If provided, the recipient is treated as an embedded (captive) recipient or signer. Use your application's client ID (user ID) for the recipient. Doing so enables the details of your application's authentication of the recipient to be connected to the recipient's signature if the signature is disputed or repudiated. Maximum length: 100 characters. |
displayFormat | string | Optional | This value determines whether the display will show an embedded or focused view experience. If set to `focused`, the display will use the focused view experience. If set to `default`, or if not set, the display will use the embedded experience. |
email | string | Optional | (Required) Specifies the email of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient. |
frameAncestors | array | Optional | An array of ancestors that can embed the frame. This property is required when [using focus view](/docs/esign-rest-api/how-to/request-signature-focused-view/). In the demo environment, include your site URL and `https://apps-d.docusign.com`. You can use `http://localhost` for local development and testing. Example: `["https://my.site.com", "https://apps-d.docusign.com"]` In the production environment, include your site URL and `https://apps.docusign.com`. HTTPS must be enabled on your site. Example: `["https://my.site.com", "https://apps.docusign.com"]` |
frameAncestors[] | string | Each item | |
messageOrigins | array | Optional | The originating domain for the signature request message. This property is required when [using focus view](/docs/esign-rest-api/how-to/request-signature-focused-view/). In the demo environment, the value must be `https://apps-d.docusign.com`. In production, the value must be `https://apps.docusign.com`. |
messageOrigins[] | string | Each item | |
pingFrequency | string | Optional | Only used if pingUrl is specified. This is the interval, in seconds, between pings on the pingUrl. The default is 300 seconds. Valid values are 60-1200 seconds. |
pingUrl | string | Optional | The client URL that the Docusign Signing experience should ping to indicate to the client that Signing is active. An HTTP GET call is executed against the client. The response from the client is ignored. The intent is for the client to reset its session timer when the request is received. |
recipientId | string | Optional | Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document. |
returnUrl | string | Optional | (Required) The URL to which the user should be redirected after the signing session has ended. Maximum Length: 470 characters. If the `returnUrl` exceeds this limit, the user is redirected to a truncated URL Be sure to include `https://` in the URL or redirecting might fail on some browsers. When Docusign redirects to this URL, it will include an `event` query parameter that your app can use: - `access_code_failed`: Recipient used incorrect access code. - `cancel`: Recipient canceled the signing operation, possibly by using the **Finish Later** option. - `decline`: Recipient declined to sign. - `exception`: A system error occurred during the signing process. - `fax_pending`: Recipient has a fax pending. - `id_check_failed`: Recipient failed an ID check. - `session_timeout`: The session timed out. An account can control this timeout by using the **Signer Session Timeout** option. - `signing_complete`: The recipient completed the signing ceremony. - `ttl_expired`: The Time To Live token for the envelope has expired. After being successfully invoked, these tokens expire after five minutes. - `viewing_complete`: The recipient completed viewing an envelope that is in a read-only/terminal state, such as completed, declined, or voided. |
securityDomain | string | Optional | The domain in which the user authenticated. |
userId | string | Optional | The user ID of the recipient. You can use either the user ID or email and user name to identify the recipient. If `userId` is used and a `clientUserId` is provided, the value in the `userId` property must match a `recipientId` (which you can retrieve with a GET recipients call) for the envelope. If a `userId` is used and a `clientUserId` is not provided, the `userId` must match the user ID of the authenticating user. |
userName | string | Optional | The username of the recipient. You can use either `email` and `userName` or `userId` to identify the recipient. |
xFrameOptions | string | Optional | Specifies whether a browser should be allowed to render a page in a frame or IFrame. Setting this property ensures that your content is not embedded into unauthorized pages or frames. Valid values are: - `deny`: The page cannot be displayed in a frame. - `same_origin`: The page can only be displayed in a frame on the same origin as the page itself. - `allow_from`: The page can only be displayed in a frame on the origin specified by the `xFrameOptionsAllowFromUrl` property. |
xFrameOptionsAllowFromUrl | string | Optional | When the value of `xFrameOptions` is `allow_from`, this property specifies the origin on which the page is allowed to display in a frame. If the value of `xFrameOptions` is `allow_from`, you must include a value for this property. |
Referenced models: Add envelope archive metadata — request body — body recipient View Request client UR Ls
Add envelope archive metadata — request body — body recipient View Request client UR Ls
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
onAccessCodeFailed | string | Optional | |
onCancel | string | Optional | |
onDecline | string | Optional | |
onException | string | Optional | |
onFaxPending | string | Optional | |
onIdCheckFailed | string | Optional | |
onSessionTimeout | string | Optional | |
onSigningComplete | string | Optional | |
onTTLExpired | string | Optional | |
onViewingComplete | string | Optional |
Add envelope archive metadata — request body — body recipients
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Specifies the envelope recipients. |
agents | array | Optional | A list of agent recipients assigned to the documents. |
agents[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients agents item |
authorizedSignatories | array | Optional | |
authorizedSignatories[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients authorized Signatories item |
carbonCopies | array | Optional | A list of carbon copy recipients assigned to the documents. |
carbonCopies[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients carbon Copies item |
certifiedDeliveries | array | Optional | A complex type containing information on a recipient the must receive the completed documents for the envelope to be completed, but the recipient does not need to sign, initial, date, or add information to any of the documents. |
certifiedDeliveries[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients certified Deliveries item |
currentRoutingOrder | string | Optional | The routing order of the current recipient. If this value equals a particular signer's routing order, it indicates that the envelope has been sent to that recipient, but he or she has not completed the required actions. |
editors | array | Optional | A list of users who can edit the envelope. |
editors[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients editors item |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
inPersonSigners | array | Optional | Specifies a signer that is in the same physical location as a DocuSign user who will act as a Signing Host for the transaction. The recipient added is the Signing Host and new separate Signer Name field appears after Sign in person is selected. |
inPersonSigners[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients in Person Signers item |
intermediaries | array | Optional | Identifies a recipient that can, but is not required to, add name and email information for recipients at the same or subsequent level in the routing order (until subsequent Agents, Editors or Intermediaries recipient types are added). |
intermediaries[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients intermediaries item |
notaries | array | Optional | A list of notary recipients on the envelope. |
notaries[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients notaries item |
notaryWitnesses | array | Optional | |
notaryWitnesses[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients notary Witnesses item |
participants | array | Optional | |
participants[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients participants item |
recipientCount | string | Optional | The number of recipients in the envelope. |
seals | array | Optional | A list of electronic seals to apply to documents. |
seals[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item |
signers | array | Optional | A list of signers on the envelope. |
signers[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients signers item |
witnesses | array | Optional | A list of signers who act as witnesses on the envelope. |
witnesses[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients witnesses item |
Referenced models: Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body recipients agents item, Add envelope archive metadata — request body — body recipients authorized Signatories item, Add envelope archive metadata — request body — body recipients carbon Copies item, Add envelope archive metadata — request body — body recipients certified Deliveries item, Add envelope archive metadata — request body — body recipients editors item, Add envelope archive metadata — request body — body recipients in Person Signers item, Add envelope archive metadata — request body — body recipients intermediaries item, Add envelope archive metadata — request body — body recipients notaries item, Add envelope archive metadata — request body — body recipients notary Witnesses item, Add envelope archive metadata — request body — body recipients participants item, Add envelope archive metadata — request body — body recipients seals item, Add envelope archive metadata — request body — body recipients signers item, Add envelope archive metadata — request body — body recipients witnesses item
Add envelope archive metadata — request body — body recipients agents item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains information about an agent recipient. An agent is a recipient who can add name and email information for recipients that appear after the agent in routing order. |
accessCode | string | Optional | If a value is provided, the recipient must enter the value as the access code to view and sign the envelope. Maximum Length: 50 characters and it must conform to the account's access code format setting. If blank, but the signer `accessCode` property is set in the envelope, then that value is used. If blank and the signer `accessCode` property is not set, then the access code is not required. |
accessCodeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
addAccessCodeToEmail | string | Optional | Optional. When **true,** the access code will be added to the email sent to the recipient. This nullifies the security measure of `accessCode` on the recipient. |
additionalNotifications | array | Optional | An array of additional notification objects. |
additionalNotifications[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item additional Notifications item |
allowSystemOverrideForLockedRecipient | string | Optional | When **true,** if the recipient is locked on a template, advanced recipient routing can override the lock. |
autoRespondedReason | string | Optional | Error message provided by the destination email system. This field is only provided if the email notification to the recipient fails to send. This property is read-only. |
bulkSendV2Recipient | string | Optional | |
clientUserId | string | Optional | Specifies whether the recipient is embedded or remote. If the `clientUserId` property is not null then the recipient is embedded. Use this field to associate the signer with their userId in your app. Authenticating the user is the responsibility of your app when you use embedded signing. If the `clientUserId` property is set and either `SignerMustHaveAccount` or `SignerMustLoginToSign` property of the account settings is set to **true,** an error is generated on sending. **Note:** This property is not returned by the [listStatusChanges](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/) endpoint. Maximum length: 100 characters. |
completedCount | string | Optional | Indicates the number of times that the recipient has been through a signing completion for the envelope. If this number is greater than 0 for a signing group, only the user who previously completed may sign again. This property is read-only. |
consentDetailsList | array | Optional | |
consentDetailsList[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients agents item consent Details List item |
customFields | array | Optional | An optional array of strings that allows the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by DocuSign. Each customField string can be a maximum of 100 characters. |
customFields[] | string | Each item | |
declinedDateTime | string | Optional | The date and time the recipient declined the document. This property is read-only. |
declinedReason | string | Optional | The reason the recipient declined the document. This property is read-only. |
deliveredDateTime | string | Optional | The date and time that the envelope was delivered to the recipient. This property is read-only. |
deliveryMethod | string | Optional | The delivery method. One of: - `email` - `fax` - `SMS` - `WhatsApp` - `offline` The `SMS` and `WhatsApp` delivery methods are limited to `signer`, `carbonCopy`, and `certifiedDelivery` recipients. **Related topics** - [Using SMS delivery with the eSignature API](/docs/esign-rest-api/esign101/concepts/sms-delivery/using-sms-esignature/) - [How to request a signature by SMS or WhatsApp delivery](/docs/esign-rest-api/how-to/request-signature-sms-whatsapp/) |
deliveryMethodMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
designatorId | string | Optional | Reserved for Docusign. |
designatorIdGuid | string | Optional | Reserved for Docusign. |
documentTemplateId | string | Optional | |
documentVisibility | array | Optional | A list of `documentVisibility` objects. Each object in the list specifies whether a document in the envelope is visible to this recipient. For the envelope to use this functionality, Document Visibility must be enabled for the account and the `enforceSignerVisibility` property must be set to **true.** |
documentVisibility[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item document Visibility item |
email | string | Optional | The email ID of the agent. Notification of the document to sign is sent to this email id. Maximum length: 100 characters. |
emailMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
emailNotification | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item email Notification |
emailRecipientPostSigningURL | string | Optional | |
embeddedRecipientStartURL | string | Optional | Specifies a sender-provided valid URL string for redirecting an embedded recipient. When using this option, the embedded recipient still receives an email from Docusign, just as a remote recipient would. When the document link in the email is clicked the recipient is redirected, through Docusign, to the supplied URL to complete their actions. When routing to the URL, the sender's system (the server responding to the URL) must request a recipient token to launch a signing session. When `SIGN_AT_DOCUSIGN`, the recipient is directed to an embedded signing or viewing process directly at Docusign. The signing or viewing action is initiated by the Docusign system and the transaction activity and Certificate of Completion records will reflect this. In all other ways the process is identical to an embedded signing or viewing operation launched by a partner. It is important to understand that in a typical embedded workflow, the authentication of an embedded recipient is the responsibility of the sending application. Docusign expects that senders will follow their own processes for establishing the recipient's identity. In this workflow the recipient goes through the sending application before the embedded signing or viewing process is initiated. However, when the sending application sets `EmbeddedRecipientStartURL=SIGN_AT_DOCUSIGN`, the recipient goes directly to the embedded signing or viewing process, bypassing the sending application and any authentication steps the sending application would use. In this case, Docusign recommends that you use one of the normal Docusign authentication features (Access Code, Phone Authentication, SMS Authentication, etc.) to verify the identity of the recipient. If the `clientUserId` property is NOT set, and the `embeddedRecipientStartURL` is set, Docusign will ignore the redirect URL and launch the standard signing process for the email recipient. Information can be appended to the embedded recipient start URL using merge fields. The available merge fields items are: `envelopeId`, `recipientId`, `recipientName`, `recipientEmail`, and `customFields`. The `customFields` property must be set for the recipient or envelope. The merge fields are enclosed in double brackets. _Example_: `http://senderHost/[[mergeField1]]/ beginSigningSession? [[mergeField2]]&[[mergeField3]]` |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
excludedDocuments | array | Optional | Specifies the documents that are not visible to this recipient. Document Visibility must be enabled for the account and the `enforceSignerVisibility` property must be set to **true** for the envelope to use this. When enforce signer visibility is enabled, documents with tabs can only be viewed by signers that have a tab on that document. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all the documents in an envelope, unless they are specifically excluded using this setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are specifically excluded using this setting when an envelope is sent. |
excludedDocuments[] | string | Each item | |
faxNumber | string | Optional | Reserved for Docusign. |
faxNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
firstName | string | Optional | The recipient's first name. Maximum Length: 50 characters. |
firstNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
fullName | string | Optional | Reserved for Docusign. |
fullNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckConfigurationName | string | Optional | The name of the authentication check to use. This value must match one of the authentication types that the account uses. The names of these authentication types appear in the web console sending interface in the Identify list for a recipient. This setting overrides any default authentication setting. Valid values are: - `Phone Auth $`: The recipient must authenticate by using two-factor authentication (2FA). You provide the phone number to use for 2FA in the `phoneAuthentication` object. - `SMS Auth $`: The recipient must authenticate via SMS. You provide the phone number to use in the `smsAuthentication` object. - `ID Check $`: The recipient must answer detailed security questions. **Example:** Your account has ID Check and SMS Authentication available. In the web console Identify list, these appear as ID Check $ and SMS Auth $. To use ID Check in an envelope, the idCheckConfigurationName should be ID Check $. For SMS, you would use SMS Auth $, and you would also need to add a phone number to the smsAuthentication node. |
idCheckConfigurationNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckInformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input |
identityVerification | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item identity Verification |
inheritEmailNotificationConfiguration | string | Optional | When **true** and the envelope recipient creates a Docusign account after signing, the Manage Account Email Notification settings are used as the default settings for the recipient's account. |
lastName | string | Optional | The recipient's last name. |
lastNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
lockedRecipientPhoneAuthEditable | string | Optional | Reserved for Docusign. |
lockedRecipientSmsEditable | string | Optional | Reserved for Docusign. |
name | string | Optional | The full legal name of the recipient. Maximum Length: 100 characters. **Note:** You must always set a value for this property in requests, even if `firstName` and `lastName` are set. |
nameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
note | string | Optional | A note sent to the recipient in the signing email. This note is unique to this recipient. In the user interface, it appears near the upper left corner of the document on the signing screen. Maximum Length: 1000 characters. |
noteMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
phoneAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item phone Authentication |
phoneNumber | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item phone Number |
proofFile | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item proof File |
recipientAttachments | array | Optional | Reserved for Docusign. |
recipientAttachments[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item |
recipientAuthenticationStatus | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status |
recipientFeatureMetadata | array | Optional | Metadata about the features that are supported for the recipient type. This property is read-only. |
recipientFeatureMetadata[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item |
recipientId | string | Optional | A local reference used to map recipients to other objects, such as specific document tabs. A `recipientId` must be either an integer or a GUID, and the `recipientId` must be unique within an envelope. For example, many envelopes assign the first recipient a `recipientId` of `1`. |
recipientIdGuid | string | Optional | The globally-unique identifier (GUID) for a specific recipient on a specific envelope. If the same recipient is associated with multiple envelopes, they will have a different GUID for each one. This property is read-only. |
recipientType | string | Optional | The recipient type, as specified by the following values: - `agent`: Agent recipients can add name and email information for recipients that appear after the agent in routing order. - `carbonCopy`: Carbon copy recipients get a copy of the envelope but don't need to sign, initial, date, or add information to any of the documents. This type of recipient can be used in any routing order. - `certifiedDelivery`: Certified delivery recipients must receive the completed documents for the envelope to be completed. They don't need to sign, initial, date, or add information to any of the documents. - `editor`: Editors have the same management and access rights for the envelope as the sender. Editors can add name and email information, add or change the routing order, set authentication options, and can edit signature/initial tabs and data fields for the remaining recipients. - `inPersonSigner`: In-person recipients are Docusign users who act as signing hosts in the same physical location as the signer. - `intermediaries`: Intermediary recipients can optionally add name and email information for recipients at the same or subsequent level in the routing order. - `seal`: Electronic seal recipients represent legal entities. - `signer`: Signers are recipients who must sign, initial, date, or add data to form fields on the documents in the envelope. - `witness`: Witnesses are recipients whose signatures affirm that the identified signers have signed the documents in the envelope. |
recipientTypeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
requireIdLookup | string | Optional | When **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity. |
requireIdLookupMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
roleName | string | Optional | Optional element. Specifies the role name associated with the recipient. This property is required when you are working with template recipients. |
routingOrder | string | Optional | Specifies the routing order of the recipient in the envelope. |
routingOrderMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
sentDateTime | string | Optional | The UTC DateTime when the envelope was sent. This property is read-only. |
signedDateTime | string | Optional | Reserved for Docusign. |
signingGroupId | string | Optional | The ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html). |
signingGroupIdMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
signingGroupName | string | Optional | Optional. The name of the signing group. Maximum Length: 100 characters. |
signingGroupType | string | Optional | |
signingGroupUsers | array | Optional | A complex type that contains information about users in the signing group. |
signingGroupUsers[] | Model | Each item | Expand Add envelope archive metadata — request body — body sender |
smsAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item sms Authentication |
socialAuthentications | array | Optional | Deprecated. |
socialAuthentications[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item social Authentications item |
status | string | Optional | The recipient's status. This property is read-only. Valid values: - `autoresponded`: The recipient's email system auto-responded to the email from Docusign. This status is used in the web console to inform senders about the bounced-back email. This recipient status is only used if **Send-on-behalf-of** is turned off for the account. - `completed`: The recipient has completed their actions (signing or other required actions if not a signer) for an envelope. - `created`: The recipient is in a draft state. This value is only associated with draft envelopes (envelopes that have a status of `created`). - `declined`: The recipient declined to sign the documents in the envelope. - `delivered`: The recipient has viewed the documents in an envelope through the Docusign signing website. This is not an email delivery of the documents in an envelope. - `faxPending`: The recipient has finished signing and the system is waiting for a fax attachment from the recipient before completing their signing step. - `sent`: The recipient has been sent an email notification that it is their turn to sign an envelope. - `signed`: The recipient has completed (signed) all required tags in an envelope. This is a temporary state during processing, after which the recipient's status automatically switches to `completed`. |
statusCode | string | Optional | The code associated with the recipient's status. This property is read-only. |
suppressEmails | string | Optional | When **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox. |
templateLocked | string | Optional | When **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients. |
templateRequired | string | Optional | When **true,** the sender may not remove the recipient. Used only when working with template recipients. |
totalTabCount | string | Optional | The total number of tabs in the documents. This property is read-only. |
userId | string | Optional | The ID of the user to access. **Note:** Users can only access their own information. A user, even one with Admin rights, cannot access another user's settings. |
webFormRecipientViewId | string | Optional |
Referenced models: Updates a template document — response body — name Metadata, Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status, Add envelope archive metadata — request body — body recipients agents item consent Details List item, Add envelope archive metadata — request body — body recipients seals item document Visibility item, Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item, Add envelope archive metadata — request body — body recipients seals item id Check Information Input, Add envelope archive metadata — request body — body template Roles item additional Notifications item, Add envelope archive metadata — request body — body recipients seals item recipient Attachments item, Add envelope archive metadata — request body — body template Roles item email Notification, Add envelope archive metadata — request body — body recipients seals item identity Verification, Add envelope archive metadata — request body — body recipients seals item phone Authentication, Add envelope archive metadata — request body — body template Roles item phone Number, Add envelope archive metadata — request body — body recipients seals item proof File, Add envelope archive metadata — request body — body recipients seals item sms Authentication, Add envelope archive metadata — request body — body recipients seals item social Authentications item, Add envelope archive metadata — request body — body sender
Add envelope archive metadata — request body — body recipients agents item consent Details List item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
consentKey | string | Optional | |
deliveryMethod | string | Optional | The delivery method. One of: - `email` - `fax` - `SMS` - `WhatsApp` - `offline` The `SMS` and `WhatsApp` delivery methods are limited to `signer`, `carbonCopy`, and `certifiedDelivery` recipients. **Related topics** - [Using SMS delivery with the eSignature API](/docs/esign-rest-api/esign101/concepts/sms-delivery/using-sms-esignature/) - [How to request a signature by SMS or WhatsApp delivery](/docs/esign-rest-api/how-to/request-signature-sms-whatsapp/) |
signerConsentStatus | string | Optional |
Add envelope archive metadata — request body — body recipients authorized Signatories item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
accessCode | string | Optional | If a value is provided, the recipient must enter the value as the access code to view and sign the envelope. Maximum Length: 50 characters and it must conform to the account's access code format setting. If blank, but the signer `accessCode` property is set in the envelope, then that value is used. If blank and the signer `accessCode` property is not set, then the access code is not required. |
accessCodeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
addAccessCodeToEmail | string | Optional | This Optional attribute indicates that the access code will be added to the email sent to the recipient; this nullifies the Security measure of Access Code on the recipient. |
additionalNotifications | array | Optional | |
additionalNotifications[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item additional Notifications item |
agentCanEditEmail | string | Optional | |
agentCanEditName | string | Optional | |
allowSystemOverrideForLockedRecipient | string | Optional | |
autoNavigation | string | Optional | |
autoRespondedReason | string | Optional | |
bulkRecipientsUri | string | Optional | Contains a URI for an endpoint that allows you to easily retrieve bulk recipient information. |
bulkSendV2Recipient | string | Optional | |
canSignOffline | string | Optional | When set to **true**, specifies that the signer can perform the signing ceremony offline. |
clientUserId | string | Optional | Specifies whether the recipient is embedded or remote. If the `clientUserId` property is not null then the recipient is embedded. Note that if the `ClientUserId` property is set and either `SignerMustHaveAccount` or `SignerMustLoginToSign` property of the account settings is set to **true**, an error is generated on sending.ng. Maximum length: 100 characters. |
completedCount | string | Optional | |
consentDetailsList | array | Optional | |
consentDetailsList[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients agents item consent Details List item |
creationReason | string | Optional | |
customFields | array | Optional | An optional array of strings that allows the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by DocuSign. Each customField string can be a maximum of 100 characters. |
customFields[] | string | Each item | |
declinedDateTime | string | Optional | The date and time the recipient declined the document. |
declinedReason | string | Optional | The reason the recipient declined the document. |
defaultRecipient | string | Optional | |
delegatedBy | Model | Optional | Expand Add envelope archive metadata — request body — body recipients signers item delegated By |
delegatedTo | array | Optional | |
delegatedTo[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients signers item delegated By |
deliveredDateTime | string | Optional | Reserved: For DocuSign use only. |
deliveryMethod | string | Optional | Reserved: For DocuSign use only. |
deliveryMethodMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
designatorId | string | Optional | |
designatorIdGuid | string | Optional | |
documentTemplateId | string | Optional | |
documentVisibility | array | Optional | |
documentVisibility[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item document Visibility item |
email | string | Optional | |
emailMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
emailNotification | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item email Notification |
emailRecipientPostSigningURL | string | Optional | |
embeddedRecipientStartURL | string | Optional | Specifies a sender provided valid URL string for redirecting an embedded recipient. When using this option, the embedded recipient still receives an email from DocuSign, just as a remote recipient would. When the document link in the email is clicked the recipient is redirected, through DocuSign, to the supplied URL to complete their actions. When routing to the URL, the sender's system (the server responding to the URL) must request a recipient token to launch a signing session. If set to `SIGN_AT_DOCUSIGN`, the recipient is directed to an embedded signing or viewing process directly at DocuSign. The signing or viewing action is initiated by the DocuSign system and the transaction activity and Certificate of Completion records will reflect this. In all other ways the process is identical to an embedded signing or viewing operation that is launched by any partner. It is important to remember that in a typical embedded workflow the authentication of an embedded recipient is the responsibility of the sending application, DocuSign expects that senders will follow their own process for establishing the recipient's identity. In this workflow the recipient goes through the sending application before the embedded signing or viewing process in initiated. However, when the sending application sets `EmbeddedRecipientStartURL=SIGN_AT_DOCUSIGN`, the recipient goes directly to the embedded signing or viewing process bypassing the sending application and any authentication steps the sending application would use. In this case, DocuSign recommends that you use one of the normal DocuSign authentication features (Access Code, Phone Authentication, SMS Authentication, etc.) to verify the identity of the recipient. If the `clientUserId` property is NOT set, and the `embeddedRecipientStartURL` is set, DocuSign will ignore the redirect URL and launch the standard signing process for the email recipient. Information can be appended to the embedded recipient start URL using merge fields. The available merge fields items are: envelopeId, recipientId, recipientName, recipientEmail, and customFields. The `customFields` property must be set fort the recipient or envelope. The merge fields are enclosed in double brackets. *Example*: `http://senderHost/[[mergeField1]]/ beginSigningSession? [[mergeField2]]&[[mergeField3]]` |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
excludedDocuments | array | Optional | Specifies the documents that are not visible to this recipient. Document Visibility must be enabled for the account and the `enforceSignerVisibility` property must be set to **true** for the envelope to use this. When enforce signer visibility is enabled, documents with tabs can only be viewed by signers that have a tab on that document. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all the documents in an envelope, unless they are specifically excluded using this setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are specifically excluded using this setting when an envelope is sent. |
excludedDocuments[] | string | Each item | |
faxNumber | string | Optional | Reserved: |
faxNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
firstName | string | Optional | The user's first name. Maximum Length: 50 characters. |
firstNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
fullName | string | Optional | |
fullNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckConfigurationName | string | Optional | Specifies authentication check by name. The names used here must be the same as the authentication type names used by the account (these name can also be found in the web console sending interface in the Identify list for a recipient,) This overrides any default authentication setting. *Example*: Your account has ID Check and SMS Authentication available and in the web console Identify list these appear as 'ID Check $' and 'SMS Auth $'. To use ID check in an envelope, the idCheckConfigurationName should be 'ID Check '. If you wanted to use SMS, it would be 'SMS Auth $' and you would need to add you would need to add phone number information to the `smsAuthentication` node. |
idCheckConfigurationNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckInformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input |
identityVerification | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item identity Verification |
inheritEmailNotificationConfiguration | string | Optional | When set to **true** and the envelope recipient creates a DocuSign account after signing, the Manage Account Email Notification settings are used as the default settings for the recipient's account. |
isBulkRecipient | string | Optional | |
isBulkRecipientMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
lastName | string | Optional | |
lastNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
lockedRecipientPhoneAuthEditable | string | Optional | |
lockedRecipientSmsEditable | string | Optional | |
name | string | Optional | |
nameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
notaryId | string | Optional | |
notarySignerEmailSent | string | Optional | |
note | string | Optional | Specifies a note that is unique to this recipient. This note is sent to the recipient via the signing email. The note displays in the signing UI near the upper left corner of the document on the signing screen. Maximum Length: 1000 characters. |
noteMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
offlineAttributes | Model | Optional | Expand Deletes recipients from a template — response body — signers item offline Attributes |
phoneAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item phone Authentication |
phoneNumber | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item phone Number |
proofFile | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item proof File |
recipientAttachments | array | Optional | Reserved: |
recipientAttachments[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item |
recipientAuthenticationStatus | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status |
recipientFeatureMetadata | array | Optional | |
recipientFeatureMetadata[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item |
recipientId | string | Optional | Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document. |
recipientIdGuid | string | Optional | |
recipientSignatureProviders | array | Optional | |
recipientSignatureProviders[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item |
recipientSuppliesTabs | string | Optional | |
recipientType | string | Optional | |
recipientTypeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
requireIdLookup | string | Optional | When set to **true**, the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity. |
requireIdLookupMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
requireSignOnPaper | string | Optional | |
requireSignerCertificate | string | Optional | |
requireUploadSignature | string | Optional | |
roleName | string | Optional | Optional element. Specifies the role name associated with the recipient.<br/><br/>This is required when working with template recipients. |
routingOrder | string | Optional | Specifies the routing order of the recipient in the envelope. |
routingOrderMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
sentDateTime | string | Optional | The date and time the envelope was sent. |
signInEachLocation | string | Optional | When set to **true**, specifies that the signer must sign in all locations. |
signInEachLocationMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
signatureInfo | Model | Optional | Expand Add envelope archive metadata — request body — body recipients signers item signature Info |
signedDateTime | string | Optional | Reserved: For DocuSign use only. |
signingGroupId | string | Optional | When set to **true** and the feature is enabled in the sender's account, the signing recipient is required to draw signatures and initials at each signature/initial tab ( instead of adopting a signature/initial style or only drawing a signature/initial once). |
signingGroupIdMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
signingGroupName | string | Optional | The display name for the signing group. Maximum Length: 100 characters. |
signingGroupType | string | Optional | |
signingGroupUsers | array | Optional | A complex type that contains information about users in the signing group. |
signingGroupUsers[] | Model | Each item | Expand Add envelope archive metadata — request body — body sender |
smsAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item sms Authentication |
socialAuthentications | array | Optional | Lists the social ID type that can be used for recipient authentication. |
socialAuthentications[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item social Authentications item |
status | string | Optional | Indicates the envelope status. Valid values are: * sent - The envelope is sent to the recipients. * created - The envelope is saved as a draft and can be modified and sent later. |
statusCode | string | Optional | |
suppressEmails | string | Optional | |
tabs | Model | Optional | Expand Add envelope archive metadata — request body — body documents item tabs |
templateLocked | string | Optional | When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. |
templateRequired | string | Optional | When set to **true**, the sender may not remove the recipient. Used only when working with template recipients. |
totalTabCount | string | Optional | |
userId | string | Optional | |
webFormRecipientViewId | string | Optional |
Referenced models: Deletes recipients from a template — response body — signers item offline Attributes, Updates a template document — response body — name Metadata, Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status, Add envelope archive metadata — request body — body recipients agents item consent Details List item, Add envelope archive metadata — request body — body recipients signers item delegated By, Add envelope archive metadata — request body — body recipients seals item document Visibility item, Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item, Add envelope archive metadata — request body — body recipients seals item id Check Information Input, Add envelope archive metadata — request body — body template Roles item additional Notifications item, Add envelope archive metadata — request body — body recipients seals item recipient Attachments item, Add envelope archive metadata — request body — body template Roles item email Notification, Add envelope archive metadata — request body — body recipients seals item identity Verification, Add envelope archive metadata — request body — body recipients seals item phone Authentication, Add envelope archive metadata — request body — body template Roles item phone Number, Add envelope archive metadata — request body — body recipients seals item proof File, Add envelope archive metadata — request body — body recipients seals item sms Authentication, Add envelope archive metadata — request body — body recipients signers item signature Info, Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item, Add envelope archive metadata — request body — body recipients seals item social Authentications item, Add envelope archive metadata — request body — body documents item tabs, Add envelope archive metadata — request body — body sender
Add envelope archive metadata — request body — body recipients carbon Copies item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains information about a carbon copy recipient. Carbon copy recipients get a copy of the envelope but don't need to sign, initial, date or add information to any of the documents. |
accessCode | string | Optional | If a value is provided, the recipient must enter the value as the access code to view and sign the envelope. Maximum Length: 50 characters and it must conform to the account's access code format setting. If blank, but the signer `accessCode` property is set in the envelope, then that value is used. If blank and the signer `accessCode` property is not set, then the access code is not required. |
accessCodeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
addAccessCodeToEmail | string | Optional | Optional. When **true,** the access code will be added to the email sent to the recipient. This nullifies the security measure of `accessCode` on the recipient. |
additionalNotifications | array | Optional | An array of additional notification objects. |
additionalNotifications[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item additional Notifications item |
agentCanEditEmail | string | Optional | Optional element. When **true,** the agents recipient associated with this recipient can change the recipient's pre-populated email address. This element is only active if enabled for the account. |
agentCanEditName | string | Optional | Optional element. When **true,** the agents recipient associated with this recipient can change the recipient's pre-populated name. This element is only active if enabled for the account. |
allowSystemOverrideForLockedRecipient | string | Optional | When **true,** if the recipient is locked on a template, advanced recipient routing can override the lock. |
autoRespondedReason | string | Optional | Error message provided by the destination email system. This field is only provided if the email notification to the recipient fails to send. This property is read-only. |
bulkSendV2Recipient | string | Optional | |
clientUserId | string | Optional | Not applicable for Carbon Copy recipients. |
completedCount | string | Optional | Indicates the number of times that the recipient has been through a signing completion for the envelope. If this number is greater than 0 for a signing group, only the user who previously completed may sign again. This property is read-only. |
consentDetailsList | array | Optional | |
consentDetailsList[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients agents item consent Details List item |
customFields | array | Optional | An optional array of strings that allows the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by DocuSign. Each customField string can be a maximum of 100 characters. |
customFields[] | string | Each item | |
declinedDateTime | string | Optional | The date and time the recipient declined the document. This property is read-only. |
declinedReason | string | Optional | The reason the recipient declined the document. This property is read-only. |
deliveredDateTime | string | Optional | The date and time that the envelope was delivered to the recipient. This property is read-only. |
deliveryMethod | string | Optional | The delivery method. One of: - `email` - `fax` - `SMS` - `WhatsApp` - `offline` The `SMS` and `WhatsApp` delivery methods are limited to `signer`, `carbonCopy`, and `certifiedDelivery` recipients. **Related topics** - [Using SMS delivery with the eSignature API](/docs/esign-rest-api/esign101/concepts/sms-delivery/using-sms-esignature/) - [How to request a signature by SMS or WhatsApp delivery](/docs/esign-rest-api/how-to/request-signature-sms-whatsapp/) |
deliveryMethodMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
designatorId | string | Optional | Reserved for Docusign. |
designatorIdGuid | string | Optional | Reserved for Docusign. |
documentTemplateId | string | Optional | |
documentVisibility | array | Optional | A list of `documentVisibility` objects. Each object in the list specifies whether a document in the envelope is visible to this recipient. For the envelope to use this functionality, Document Visibility must be enabled for the account and the `enforceSignerVisibility` property must be set to **true.** |
documentVisibility[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item document Visibility item |
email | string | Optional | The recipient's email address. Notification of the document to sign is sent to this email address. Maximum length: 100 characters. |
emailMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
emailNotification | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item email Notification |
emailRecipientPostSigningURL | string | Optional | |
embeddedRecipientStartURL | string | Optional | Specifies a sender-provided valid URL string for redirecting an embedded recipient. When using this option, the embedded recipient still receives an email from Docusign, just as a remote recipient would. When the document link in the email is clicked the recipient is redirected, through Docusign, to the supplied URL to complete their actions. When routing to the URL, the sender's system (the server responding to the URL) must request a recipient token to launch a signing session. When `SIGN_AT_DOCUSIGN`, the recipient is directed to an embedded signing or viewing process directly at Docusign. The signing or viewing action is initiated by the Docusign system and the transaction activity and Certificate of Completion records will reflect this. In all other ways the process is identical to an embedded signing or viewing operation launched by a partner. It is important to understand that in a typical embedded workflow, the authentication of an embedded recipient is the responsibility of the sending application. Docusign expects that senders will follow their own processes for establishing the recipient's identity. In this workflow the recipient goes through the sending application before the embedded signing or viewing process is initiated. However, when the sending application sets `EmbeddedRecipientStartURL=SIGN_AT_DOCUSIGN`, the recipient goes directly to the embedded signing or viewing process, bypassing the sending application and any authentication steps the sending application would use. In this case, Docusign recommends that you use one of the normal Docusign authentication features (Access Code, Phone Authentication, SMS Authentication, etc.) to verify the identity of the recipient. If the `clientUserId` property is NOT set, and the `embeddedRecipientStartURL` is set, Docusign will ignore the redirect URL and launch the standard signing process for the email recipient. Information can be appended to the embedded recipient start URL using merge fields. The available merge fields items are: `envelopeId`, `recipientId`, `recipientName`, `recipientEmail`, and `customFields`. The `customFields` property must be set for the recipient or envelope. The merge fields are enclosed in double brackets. _Example_: `http://senderHost/[[mergeField1]]/ beginSigningSession? [[mergeField2]]&[[mergeField3]]` |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
excludedDocuments | array | Optional | Specifies the documents that are not visible to this recipient. Document Visibility must be enabled for the account and the `enforceSignerVisibility` property must be set to **true** for the envelope to use this. When enforce signer visibility is enabled, documents with tabs can only be viewed by signers that have a tab on that document. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all the documents in an envelope, unless they are specifically excluded using this setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are specifically excluded using this setting when an envelope is sent. |
excludedDocuments[] | string | Each item | |
faxNumber | string | Optional | Reserved for Docusign. |
faxNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
firstName | string | Optional | The recipient's first name. Maximum Length: 50 characters. |
firstNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
fullName | string | Optional | Reserved for Docusign. |
fullNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckConfigurationName | string | Optional | The name of the authentication check to use. This value must match one of the authentication types that the account uses. The names of these authentication types appear in the web console sending interface in the Identify list for a recipient. This setting overrides any default authentication setting. Valid values are: - `Phone Auth $`: The recipient must authenticate by using two-factor authentication (2FA). You provide the phone number to use for 2FA in the `phoneAuthentication` object. - `SMS Auth $`: The recipient must authenticate via SMS. You provide the phone number to use in the `smsAuthentication` object. - `ID Check $`: The recipient must answer detailed security questions. **Example:** Your account has ID Check and SMS Authentication available. In the web console Identify list, these appear as ID Check $ and SMS Auth $. To use ID Check in an envelope, the idCheckConfigurationName should be ID Check $. For SMS, you would use SMS Auth $, and you would also need to add a phone number to the smsAuthentication node. |
idCheckConfigurationNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckInformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input |
identityVerification | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item identity Verification |
inheritEmailNotificationConfiguration | string | Optional | When **true** and the envelope recipient creates a Docusign account after signing, the Manage Account Email Notification settings are used as the default settings for the recipient's account. |
lastName | string | Optional | The recipient's last name. |
lastNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
linkedAccountConfigurationId | string | Optional | |
lockedRecipientPhoneAuthEditable | string | Optional | Reserved for Docusign. |
lockedRecipientSmsEditable | string | Optional | Reserved for Docusign. |
name | string | Optional | The full legal name of the recipient. Maximum Length: 100 characters. **Note:** You must always set a value for this property in requests, even if `firstName` and `lastName` are set. |
nameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
note | string | Optional | A note sent to the recipient in the signing email. This note is unique to this recipient. In the user interface, it appears near the upper left corner of the document on the signing screen. Maximum Length: 1000 characters. |
noteMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
phoneAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item phone Authentication |
phoneNumber | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item phone Number |
proofFile | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item proof File |
recipientAttachments | array | Optional | Reserved for Docusign. |
recipientAttachments[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item |
recipientAuthenticationStatus | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status |
recipientFeatureMetadata | array | Optional | Metadata about the features that are supported for the recipient type. This property is read-only. |
recipientFeatureMetadata[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item |
recipientId | string | Optional | A local reference used to map recipients to other objects, such as specific document tabs. A `recipientId` must be either an integer or a GUID, and the `recipientId` must be unique within an envelope. For example, many envelopes assign the first recipient a `recipientId` of `1`. |
recipientIdGuid | string | Optional | The globally-unique identifier (GUID) for a specific recipient on a specific envelope. If the same recipient is associated with multiple envelopes, they will have a different GUID for each one. This property is read-only. |
recipientType | string | Optional | The recipient type, as specified by the following values: - `agent`: Agent recipients can add name and email information for recipients that appear after the agent in routing order. - `carbonCopy`: Carbon copy recipients get a copy of the envelope but don't need to sign, initial, date, or add information to any of the documents. This type of recipient can be used in any routing order. - `certifiedDelivery`: Certified delivery recipients must receive the completed documents for the envelope to be completed. They don't need to sign, initial, date, or add information to any of the documents. - `editor`: Editors have the same management and access rights for the envelope as the sender. Editors can add name and email information, add or change the routing order, set authentication options, and can edit signature/initial tabs and data fields for the remaining recipients. - `inPersonSigner`: In-person recipients are Docusign users who act as signing hosts in the same physical location as the signer. - `intermediaries`: Intermediary recipients can optionally add name and email information for recipients at the same or subsequent level in the routing order. - `seal`: Electronic seal recipients represent legal entities. - `signer`: Signers are recipients who must sign, initial, date, or add data to form fields on the documents in the envelope. - `witness`: Witnesses are recipients whose signatures affirm that the identified signers have signed the documents in the envelope. |
recipientTypeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
requireIdLookup | string | Optional | When **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity. |
requireIdLookupMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
roleName | string | Optional | Optional element. Specifies the role name associated with the recipient. This property is required when you are working with template recipients. |
routingOrder | string | Optional | Specifies the routing order of the recipient in the envelope. |
routingOrderMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
sentDateTime | string | Optional | The UTC DateTime when the envelope was sent. This property is read-only. |
signedDateTime | string | Optional | Reserved for Docusign. |
signingGroupId | string | Optional | The ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html). |
signingGroupIdMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
signingGroupName | string | Optional | Optional. The name of the signing group. Maximum Length: 100 characters. |
signingGroupType | string | Optional | |
signingGroupUsers | array | Optional | A complex type that contains information about users in the signing group. |
signingGroupUsers[] | Model | Each item | Expand Add envelope archive metadata — request body — body sender |
smsAuthentication | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item sms Authentication |
socialAuthentications | array | Optional | Deprecated. |
socialAuthentications[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item social Authentications item |
status | string | Optional | The recipient's status. This property is read-only. Valid values: - `autoresponded`: The recipient's email system auto-responded to the email from Docusign. This status is used in the web console to inform senders about the bounced-back email. This recipient status is only used if **Send-on-behalf-of** is turned off for the account. - `completed`: The recipient has completed their actions (signing or other required actions if not a signer) for an envelope. - `created`: The recipient is in a draft state. This value is only associated with draft envelopes (envelopes that have a status of `created`). - `declined`: The recipient declined to sign the documents in the envelope. - `delivered`: The recipient has viewed the documents in an envelope through the Docusign signing website. This is not an email delivery of the documents in an envelope. - `faxPending`: The recipient has finished signing and the system is waiting for a fax attachment from the recipient before completing their signing step. - `sent`: The recipient has been sent an email notification that it is their turn to sign an envelope. - `signed`: The recipient has completed (signed) all required tags in an envelope. This is a temporary state during processing, after which the recipient's status automatically switches to `completed`. |
statusCode | string | Optional | The code associated with the recipient's status. This property is read-only. |
suppressEmails | string | Optional | When **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox. |
tabs | Model | Optional | Expand Add envelope archive metadata — request body — body documents item tabs |
templateLocked | string | Optional | When **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients. |
templateRequired | string | Optional | When **true,** the sender may not remove the recipient. Used only when working with template recipients. |
totalTabCount | string | Optional | The total number of tabs in the documents. This property is read-only. |
userId | string | Optional | The ID of the user to access. **Note:** Users can only access their own information. A user, even one with Admin rights, cannot access another user's settings. |
webFormRecipientViewId | string | Optional |
Referenced models: Updates a template document — response body — name Metadata, Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status, Add envelope archive metadata — request body — body recipients agents item consent Details List item, Add envelope archive metadata — request body — body recipients seals item document Visibility item, Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item, Add envelope archive metadata — request body — body recipients seals item id Check Information Input, Add envelope archive metadata — request body — body template Roles item additional Notifications item, Add envelope archive metadata — request body — body recipients seals item recipient Attachments item, Add envelope archive metadata — request body — body template Roles item email Notification, Add envelope archive metadata — request body — body recipients seals item identity Verification, Add envelope archive metadata — request body — body recipients seals item phone Authentication, Add envelope archive metadata — request body — body template Roles item phone Number, Add envelope archive metadata — request body — body recipients seals item proof File, Add envelope archive metadata — request body — body recipients seals item sms Authentication, Add envelope archive metadata — request body — body recipients seals item social Authentications item, Add envelope archive metadata — request body — body documents item tabs, Add envelope archive metadata — request body — body sender