DocuSign: Esignature schemas (part 11)
24 DocuSign schemas with complete fields and constraints.
← Esignature operations · All schemas
Add envelope archive metadata — request body — body recipients notaries 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 | 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. |
autoNavigation | string | Optional | When **true,** autonavigation is set for the recipient. |
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. |
bulkRecipientsUri | string | Optional | Reserved for Docusign. |
bulkSendV2Recipient | string | Optional | |
canNotaryCorrectEnvelope | string | Optional | |
canSignOffline | string | Optional | When **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. 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 |
creationReason | string | Optional | The reason why the item was created. |
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. |
defaultRecipient | string | Optional | When **true,** this recipient is the default recipient and any tabs generated by the transformPdfFields option are mapped to this recipient. |
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 | 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 user'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. |
isBulkRecipient | string | Optional | Reserved for Docusign. |
isBulkRecipientMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
lastName | string | Optional | The user's last name. Maximum Length: 50 characters. |
lastNameMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
liveOakStartURL | string | Optional | URL that directs the recipient to LiveOak to complete the remote online notarization process. This property is read-only. |
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 |
notaryId | string | Optional | Not applicable to Notary tab. |
notarySignerEmailSent | string | Optional | |
notarySigners | array | Optional | An array of strings that correspond to the `recipientId` of each signer in the notary group. This property is read-only. |
notarySigners[] | string | Each item | |
notarySourceType | string | Optional | Valid values: - `firstparty`: Set this value if using the [remote online notary](/docs/notary-api/how-to/send-signature-request-notary-group/) (RON) feature. - `thirdparty`: Set this value if using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand/) feature. |
notaryThirdPartyPartner | string | Optional | Set this value to `onenotary` if using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand/) feature. |
notaryType | string | Optional | Set this value to `remote` if using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand/) feature. |
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 |
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 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. |
recipientSignatureProviders | array | Optional | The default signature provider is the Docusign Electronic signature system. This parameter is used to specify one or more Standards Based Signature (digital signature) providers for the signer to use. [More information.](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/) |
recipientSignatureProviders[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item |
recipientSuppliesTabs | string | Optional | When **true,** specifies that the recipient creates the tabs. |
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 |
requireSignOnPaper | string | Optional | When **true,** the signer must print, sign, and upload or fax the signed documents to Docusign. |
requireSignerCertificate | string | Optional | By default, Docusign signers create electronic signatures. This field can be used to require the signer to use a SAFE-BioPharma digital certificate for signing. This parameter should only be used to select a SAFE-BioPharma certificate. New integrations should use the `recipientSignatureProviders` parameter for other types of digital certificates. Set this parameter to `safe` to use a SAFE-BioPharma certificate. The signer must be enrolled in the SAFE program to sign with a SAFE certificate. |
requireUploadSignature | string | Optional | When **true,** the signer is required to upload a new signature, even if they have a pre-adopted signature in their personal Docusign account. |
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. |
signInEachLocation | string | Optional | When **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). |
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. |
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 | 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 | Reserved for Docusign. |
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: 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 notary Witnesses 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 | |
type | string | Optional | |
userId | string | Optional | |
webFormRecipientViewId | string | Optional | |
witnessFor | string | Optional | |
witnessForGuid | 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 participants 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 | 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 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 | |
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 |
faxNumber | string | Optional | Reserved for Docusign. |
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 | 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 user's last name. Maximum Length: 50 characters. |
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 | |
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 |
participateFor | string | Optional | |
participateForGuid | string | Optional | |
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 | 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 | Reserved for Docusign. |
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 seals item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Specifies one or more electronic seals to apply on documents. An electronic seal recipient is a legal entity rather than an actual person. Electronic Seals can be used by organizations and governments to show evidence of origin and integrity of documents. Even though electronic seals can be represented by a tab in a document, they do not require user interaction and apply automatically in the order specified by the sender. The sender is therefore the person authorizing usage of the electronic seal in the flow. Example: ```text "recipients": { "seals": [ { "recipientId": "1", "routingOrder" : 1, "recipientSignatureProviders": [ { "sealName": "52e9d968-xxxx-xxxx-xxxx-4682bc45c106" } ] } ] }, . . . ``` For more information about Electronic Seals, see [Apply Electronic Seals to Your Documents](https://support.docusign.com/s/document-item?bundleId=xcm1643837555908&topicId=isl1578456577247.html). |
accessCode | string | Optional | Not applicable. |
accessCodeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
addAccessCodeToEmail | string | Optional | Not applicable. |
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. |
completedCount | string | Optional | Not applicable. |
customFields | array | Optional | Not applicable. |
customFields[] | string | Each item | |
declinedDateTime | string | Optional | Not applicable. |
declinedReason | string | Optional | Not applicable. |
deliveredDateTime | string | Optional | Not applicable. |
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 | Not applicable. |
documentVisibility[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item document Visibility item |
emailNotification | Model | Optional | Expand Add envelope archive metadata — request body — body template Roles item email Notification |
embeddedRecipientStartURL | string | Optional | Not applicable. |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
faxNumber | string | Optional | Reserved for Docusign. |
faxNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
idCheckConfigurationName | string | Optional | Not applicable. |
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 | Not applicable. |
lockedRecipientPhoneAuthEditable | string | Optional | Reserved for Docusign. |
lockedRecipientSmsEditable | string | Optional | Reserved for Docusign. |
name | string | Optional | Not applicable. |
note | string | Optional | Not applicable. |
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 |
proofFile | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item proof File |
recipientAttachments | array | Optional | Not applicable. |
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 | Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document. |
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. |
recipientSignatureProviders | array | Optional | (Required) Indicates which electronic seal to apply on documents when creating an envelope. |
recipientSignatureProviders[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item |
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 | Not applicable. |
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 | (Optional, default: 1) Specifies the routing order of the electronic seal in the envelope. The routing order assigned to your electronic seal cannot be shared with another recipient. It is recommended that you set a routing order for your electronic seals. |
routingOrderMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
sentDateTime | string | Optional | Not applicable. |
signedDateTime | string | Optional | Not applicable. |
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 | Not applicable. |
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 | Not applicable. |
userId | string | Optional | Not applicable. |
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 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 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 recipients seals item proof File, Add envelope archive metadata — request body — body recipients seals item sms Authentication, 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 recipients seals item document Visibility item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | This object configures a recipient's read/write access to a document. |
documentId | string | Optional | Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute. |
errorDetails | Model | Optional | Expand Add envelope archive metadata — response body — error Details |
recipientId | string | Optional | The ID of the recipient to whom the document visibility setting is applied. This value should match the `recipientId` defined in the recipient object. |
rights | string | Optional | Indicates whether the document is editable: - `editable` - `read_only` |
visible | string | Optional | When **true,** the document is visible to the recipient. |
Referenced models: Add envelope archive metadata — response body — error Details
Add envelope archive metadata — request body — body recipients seals item id Check Information Input
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex element that contains input information related to a recipient ID check. |
addressInformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input |
dobInformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input dob Information Input |
ssn4InformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn4 Information Input |
ssn9InformationInput | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn9 Information Input |
Referenced models: Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input, Add envelope archive metadata — request body — body recipients seals item id Check Information Input dob Information Input, Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn4 Information Input, Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn9 Information Input
Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains address input information. |
addressInformation | Model | Optional | Expand Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input address Information |
displayLevelCode | string | Optional | Specifies the display level for the recipient. Valid values are: * ReadOnly * Editable * DoNotDisplay |
receiveInResponse | string | Optional | A Boolean value that specifies whether the information must be returned in the response. |
Referenced models: Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input address Information
Add envelope archive metadata — request body — body recipients seals item id Check Information Input address Information Input address Information
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains address information. |
address1 | string | Optional | The first line of the user's address. Maximum length: 100 characters. |
address2 | string | Optional | The second line of the user's address. Maximum length: 100 characters. |
city | string | Optional | The user's city. Maximum length: 40 characters. |
country | string | Optional | The user's country. Maximum length: 50 characters. |
fax | string | Optional | A Fax number associated with the address if one is available. |
phone | string | Optional | A phone number associated with the address. |
postalCode | string | Optional | The user's postal code. Maximum length: 20 characters. |
stateOrProvince | string | Optional | The user's state or province. Maximum length: 40 characters. |
zipPlus4 | string | Optional |
Add envelope archive metadata — request body — body recipients seals item id Check Information Input dob Information Input
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Complex type containing: * dateOfBirth * displayLevelCode * receiveInResponse |
dateOfBirth | string | Optional | Specifies the recipient's date, month, and year of birth. |
displayLevelCode | string | Optional | Specifies the display level for the recipient. Valid values are: * ReadOnly * Editable * DoNotDisplay |
receiveInResponse | string | Optional | A Boolean value that specifies whether the information must be returned in the response. |
Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn4 Information Input
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
displayLevelCode | string | Optional | Specifies the display level for the recipient. Valid values are: * ReadOnly * Editable * DoNotDisplay |
receiveInResponse | string | Optional | A Boolean value that specifies whether the information must be returned in the response. |
ssn4 | string | Optional | The last four digits of the recipient's Social Security Number (SSN). |
Add envelope archive metadata — request body — body recipients seals item id Check Information Input ssn9 Information Input
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
displayLevelCode | string | Optional | Specifies the display level for the recipient. Valid values are: * ReadOnly * Editable * DoNotDisplay |
ssn9 | string | Optional | The recipient's full Social Security Number (SSN). |
Add envelope archive metadata — request body — body recipients seals item identity Verification
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Specifies ID Verification applied on an envelope by workflow ID. See the [list](/docs/esign-rest-api/reference/accounts/identityverifications/list/) method in the [IdentityVerifications](/docs/esign-rest-api/reference/accounts/identityverifications/) resource for more information on how to retrieve workflow IDs available for an account. This can be used in addition to other [recipient authentication](https://support.docusign.com/en/guides/ndse-user-guide-recipient-authentication) methods. |
hasAutoAttachedRiskAssessment | string | Optional | |
inputOptions | array | Optional | |
inputOptions[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item |
workflowId | string | Optional | ID of the Identity Verification worklow used to verify recipients' identity. This ID must match one of the [workflowId](/docs/esign-rest-api/reference/accounts/identityverifications/list/) available to your account. |
workflowIdMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
workflowLabel | string | Optional |
Referenced models: Updates a template document — response body — name Metadata, Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item
Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
name | string | Optional | |
phoneNumberList | array | Optional | |
phoneNumberList[] | Model | Each item | Expand Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item phone Number List item |
stringValue | string | Optional | |
valueType | string | Optional |
Referenced models: Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item phone Number List item
Add envelope archive metadata — request body — body recipients seals item identity Verification input Options item phone Number List item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
countryCode | string | Optional | The numeric country calling code for the phone number. For example, the country calling code for the US and Canada is 1. For the UK, the country calling code is 44. Do not include the + symbol. |
countryCodeLock | string | Optional | |
countryCodeMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
extension | string | Optional | The telephone extension, if any. |
extensionMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
number | string | Optional | The telephone number. Use only the digits `0`-`9`. Remove any non-numeric characters. Do not include the `countryCode`. For US, Canada, and other [North American Numbering Plan](https://en.wikipedia.org/wiki/North_American_Numbering_Plan) countries, do not include a leading `1` or `0`. |
numberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
Referenced models: Updates a template document — response body — name Metadata
Add envelope archive metadata — request body — body recipients seals item phone Authentication
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex type that contains the elements: - `recipMayProvideNumber`: A Boolean value that specifies whether the recipient can use the phone number of their choice. - `senderProvidedNumbers`: A list of phone numbers that the recipient can use. - `recordVoicePrint`: Reserved for Docusign. - `validateRecipProvidedNumber`: Reserved for Docusign. |
recipMayProvideNumber | string | Optional | Boolean. When **true,** the recipient can supply a phone number their choice. |
recipMayProvideNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
recordVoicePrint | string | Optional | Reserved for Docusign. |
recordVoicePrintMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
senderProvidedNumbers | array | Optional | An array containing a list of phone numbers that the recipient can use for SMS text authentication. |
senderProvidedNumbers[] | string | Each item | |
senderProvidedNumbersMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
validateRecipProvidedNumber | string | Optional | Reserved for Docusign. |
validateRecipProvidedNumberMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
Referenced models: Updates a template document — response body — name Metadata
Add envelope archive metadata — request body — body recipients seals item proof File
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The proof file of the recipient. [ID Evidence](/docs/idevidence-api/) uses proof files to store the identification data that recipients submit when verifying their ID with [ID Verification](/docs/esign-rest-api/esign101/concepts/documents/) |
hasIdentityAttempts | string | Optional | |
isInProofFile | string | Optional | Indicates whether a proof file is available for this recipient. |
Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
attachmentId | string | Optional | The unique identifier for the attachment. |
attachmentType | string | Optional | Specifies the type of the attachment for the recipient. Possible values are: - `.htm` - `.xml` |
data | string | Optional | A Base64-encoded representation of the attachment that is used to upload and download the file. File attachments may be up to 50 MB in size. |
label | string | Optional | An optional label for the attachment. |
name | string | Optional | The name of the attachment. |
remoteUrl | string | Optional | The URL of a previously staged chunked upload. Using a chunked upload enables you to stage a large, chunkable temp file. You then use the `remoteUrl` property to reference the chunked upload as the content in attachment and document-related requests. The `remoteUrl` property cannot be used for downloads. |
Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
Referenced models: Deletes recipients from a template — response body — seals item recipient Authentication Status ofac Result
Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
availabilty | string | Optional | |
featureName | string | Optional |
Add envelope archive metadata — request body — body recipients seals item sms Authentication
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Contains the element senderProvidedNumbers which is an Array of phone numbers the recipient can use for SMS text authentication. |
senderProvidedNumbers | array | Optional | An array containing a list of phone numbers that the recipient can use for SMS text authentication. |
senderProvidedNumbers[] | string | Each item | |
senderProvidedNumbersMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
Referenced models: Updates a template document — response body — name Metadata
Add envelope archive metadata — request body — body recipients seals item social Authentications item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
authentication | string | Optional | Reserved for Docusign. |
Add envelope archive metadata — request body — body recipients signers item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A complex type containing information about a signer recipient. A signer is a recipient who must take action on a document, such as sign, initial, date, or add data to form fields on a document. |
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 agent 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. When **true,** the agent 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. |
autoNavigation | string | Optional | When **true,** autonavigation is set for the recipient. |
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. |
bulkRecipientsUri | string | Optional | Reserved for Docusign. |
bulkSendV2Recipient | string | Optional | |
canSignOffline | string | Optional | When **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. 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 |
creationReason | string | Optional | The reason why the item was created. |
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 recipient may be assigned a maximum of 3 custom fields, and 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. |
defaultRecipient | string | Optional | When **true,** this recipient is the default recipient and any tabs generated by the transformPdfFields option are mapped to this recipient. |
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 | 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. The system sends notifications about the documents to sign to this 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 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. |
isBulkRecipient | string | Optional | When **true,** this signer is a bulk recipient and the recipient information is contained in a bulk recipient file. Note that when this is true the email and name for the recipient becomes [bulk@example.com](mailto:bulk@example.com) and "Bulk Recipient". These fields can not be changed for the bulk recipient. |
isBulkRecipientMetadata | Model | Optional | Expand Updates a template document — response body — name Metadata |
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 |
notaryId | string | Optional | The `recipientId` of the notary for this signer. |
notarySignerEmailSent | string | Optional | |
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 |
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 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. |
recipientSignatureProviders | array | Optional | The default signature provider is the Docusign Electronic signature system. This parameter is used to specify one or more Standards Based Signature (digital signature) providers for the signer to use. [More information.](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/) |
recipientSignatureProviders[] | Model | Each item | Expand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item |
recipientSuppliesTabs | string | Optional | When **true,** specifies that the recipient creates the tabs. |
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 |
requireSignOnPaper | string | Optional | When **true,** the signer must print, sign, and upload or fax the signed documents to Docusign. |
requireSignerCertificate | string | Optional | Sets the type of signer certificate required for signing. If left blank, no certificate is required. Only one type of certificate can be set for a signer. Valid values: - `docusign_express`: Requires a Docusign Express certificate. - `safe`: Requires a SAFE-BioPharma certificate. - `open_trust`: Requires an OpenTrust certificate. **Important:** There are certain rules and restrictions that must be followed when requiring OpenTrust digital signatures. See [ML:OpenTrust Rules and Restrictions] for more information. |
requireUploadSignature | string | Optional | When **true,** the signer is required to upload a new signature, even if they have a pre-adopted signature in their personal Docusign account. |
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. |
signInEachLocation | string | Optional | When **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). |
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. |
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 | Specifies the status of the recipient at the time of the request. This property is read-only. Possible values are: - `created`: The recipient is in a draft state. This is only associated with draft envelopes (envelopes with a created status). - `sent`: The recipient has been sent an email notification that it is their turn to sign an envelope. - `delivered`: The recipient has viewed the documents in an envelope through the Docusign signing web site. This is not an email delivery of the documents in an envelope. - `signed`; The recipient has completed (performed all required interactions, such as signing or entering data) all required tags in an envelope. This is a temporary state during processing, after which the recipient is automatically moved to completed. - `declined`: The recipient declined to sign the documents in the envelope. - `completed`: The recipient has completed their actions (signing or other required actions if not a signer) for an envelope. - `faxpending`: The recipient has finished signing and the system is waiting a fax attachment by the recipient before completing their signing step. - `autoresponded`: The recipient's email system auto-responded to the email from Docusign. This status is used by the Docusign webapp (also known as the Docusign console) to inform senders about the auto-responded email. |
statusCode | string | Optional | Reserved for Docusign. |
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: 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 signers item delegated By
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
email | string | Optional | |
name | string | Optional | |
userAuthorizationId | string | Optional | |
userId | string | Optional |
Add envelope archive metadata — request body — body recipients signers item signature Info
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Allows the sender to pre-specify the signature name, signature initials and signature font used in the signature stamp for the recipient. Used only with recipient types In Person Signers and Signers. |
fontStyle | string | Optional | The font type to use for the signature if the signature is not drawn. The following font styles are supported. The quotes are to indicate that these values are strings, not `enums`. - `"1_DocuSign"` - `"2_DocuSign"` - `"3_DocuSign"` - `"4_DocuSign"` - `"5_DocuSign"` - `"6_DocuSign"` - `"7_DocuSign"` - `"8_DocuSign"` - `"Mistral"` - `"Rage Italic"` |
signatureInitials | string | Optional | Specifies the user's signature in initials format. |
signatureName | string | Optional | Specifies the user's signature name. |