Skip to content

DocuSign: Esignature schemas (part 10)

5 DocuSign schemas with complete fields and constraints.

← Esignature operations · All schemas

Add envelope archive metadata — request body — body recipients certified Deliveries item

FieldTypePresenceDescription and constraints
$objectRootContains information about a certified delivery recipient. Certified delivery recipients must receive the completed documents for the envelope to be completed. However, they don't need to sign, initial, date or add information to any of the documents.
accessCodestringOptionalIf 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.
accessCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
addAccessCodeToEmailstringOptionalOptional. 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.
additionalNotificationsarrayOptionalAn array of additional notification objects.
additionalNotifications[]ModelEach itemExpand Add envelope archive metadata — request body — body template Roles item additional Notifications item
agentCanEditEmailstringOptionalOptional 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.
agentCanEditNamestringOptionalOptional 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.
allowSystemOverrideForLockedRecipientstringOptionalWhen **true,** if the recipient is locked on a template, advanced recipient routing can override the lock.
autoRespondedReasonstringOptionalError 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.
bulkSendV2RecipientstringOptional
clientUserIdstringOptionalSpecifies 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.
completedCountstringOptionalIndicates 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.
consentDetailsListarrayOptional
consentDetailsList[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients agents item consent Details List item
customFieldsarrayOptionalAn 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[]stringEach item
declinedDateTimestringOptionalThe date and time the recipient declined the document. This property is read-only.
declinedReasonstringOptionalThe reason the recipient declined the document. This property is read-only.
deliveredDateTimestringOptionalThe date and time that the envelope was delivered to the recipient. This property is read-only.
deliveryMethodstringOptionalThe 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/)
deliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
designatorIdstringOptionalReserved for Docusign.
designatorIdGuidstringOptionalReserved for Docusign.
documentTemplateIdstringOptional
documentVisibilityarrayOptionalA 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[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item document Visibility item
emailstringOptionalThe recipient's email address.
emailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailNotificationModelOptionalExpand Add envelope archive metadata — request body — body template Roles item email Notification
emailRecipientPostSigningURLstringOptional
embeddedRecipientStartURLstringOptionalSpecifies 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]]`
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
excludedDocumentsarrayOptionalSpecifies 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[]stringEach item
faxNumberstringOptionalReserved for Docusign.
faxNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
firstNamestringOptionalThe recipient's first name. Maximum Length: 50 characters.
firstNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
fullNamestringOptionalReserved for Docusign.
fullNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckConfigurationNamestringOptionalThe 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.
idCheckConfigurationNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckInformationInputModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item id Check Information Input
identityVerificationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item identity Verification
inheritEmailNotificationConfigurationstringOptionalWhen **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.
lastNamestringOptionalThe recipient's last name.
lastNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
lockedRecipientPhoneAuthEditablestringOptionalReserved for Docusign.
lockedRecipientSmsEditablestringOptionalReserved for Docusign.
namestringOptionalThe 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.
nameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
notestringOptionalA 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.
noteMetadataModelOptionalExpand Updates a template document — response body — name Metadata
phoneAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item phone Authentication
phoneNumberModelOptionalExpand Add envelope archive metadata — request body — body template Roles item phone Number
proofFileModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item proof File
recipientAttachmentsarrayOptionalReserved for Docusign.
recipientAttachments[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
recipientAuthenticationStatusModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
recipientFeatureMetadataarrayOptionalMetadata about the features that are supported for the recipient type. This property is read-only.
recipientFeatureMetadata[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
recipientIdstringOptionalA 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`.
recipientIdGuidstringOptionalThe 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.
recipientTypestringOptionalThe 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.
recipientTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireIdLookupstringOptionalWhen **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.
requireIdLookupMetadataModelOptionalExpand Updates a template document — response body — name Metadata
roleNamestringOptionalOptional element. Specifies the role name associated with the recipient.

This property is required when you are working with template recipients.
routingOrderstringOptionalSpecifies the routing order of the recipient in the envelope.
routingOrderMetadataModelOptionalExpand Updates a template document — response body — name Metadata
sentDateTimestringOptionalThe UTC DateTime when the envelope was sent. This property is read-only.
signedDateTimestringOptionalReserved for Docusign.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).
signingGroupIdMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupNamestringOptionalOptional. The name of the signing group.

Maximum Length: 100 characters.
signingGroupTypestringOptional
signingGroupUsersarrayOptionalA complex type that contains information about users in the signing group.
signingGroupUsers[]ModelEach itemExpand Add envelope archive metadata — request body — body sender
smsAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item sms Authentication
socialAuthenticationsarrayOptionalDeprecated.
socialAuthentications[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item social Authentications item
statusstringOptionalThe status of the recipient. 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`.
statusCodestringOptionalThe code associated with the recipient's status. This property is read-only.
suppressEmailsstringOptionalWhen **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox.
templateLockedstringOptionalWhen **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients.
templateRequiredstringOptionalWhen **true,** the sender may not remove the recipient. Used only when working with template recipients.
totalTabCountstringOptionalThe total number of tabs in the documents. This property is read-only.
userIdstringOptionalThe 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.
webFormRecipientViewIdstringOptional

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 editors item

FieldTypePresenceDescription and constraints
$objectRootA complex type defining the management and access rights of a recipient assigned as an editor on the envelope. Editors have the same management and access rights for the envelope as the sender. They can make changes to the envelope as if they were using the Correct feature. This recipient can add name and email information, add or change the routing order and set authentication options for the remaining recipients. Additionally, this recipient can edit signature/initial tabs and text tabs for the remaining recipients.
accessCodestringOptionalIf 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.
accessCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
addAccessCodeToEmailstringOptionalOptional. 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.
additionalNotificationsarrayOptionalAn array of additional notification objects.
additionalNotifications[]ModelEach itemExpand Add envelope archive metadata — request body — body template Roles item additional Notifications item
allowSystemOverrideForLockedRecipientstringOptionalWhen **true,** if the recipient is locked on a template, advanced recipient routing can override the lock.
autoRespondedReasonstringOptionalError 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.
bulkSendV2RecipientstringOptional
clientUserIdstringOptionalSpecifies 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.
completedCountstringOptionalIndicates 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.
consentDetailsListarrayOptional
consentDetailsList[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients agents item consent Details List item
customFieldsarrayOptionalAn 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[]stringEach item
declinedDateTimestringOptionalThe date and time the recipient declined the document. This property is read-only.
declinedReasonstringOptionalThe reason the recipient declined the document. This property is read-only.
deliveredDateTimestringOptionalThe date and time that the envelope was delivered to the recipient. This property is read-only.
deliveryMethodstringOptionalThe 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/)
deliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
designatorIdstringOptionalReserved for Docusign.
designatorIdGuidstringOptionalReserved for Docusign.
documentTemplateIdstringOptional
documentVisibilityarrayOptionalA 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[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item document Visibility item
emailstringOptionalThe recipient's email address. Notification of the document to sign is sent to this email address.

Maximum length: 100 characters.
emailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailNotificationModelOptionalExpand Add envelope archive metadata — request body — body template Roles item email Notification
emailRecipientPostSigningURLstringOptional
embeddedRecipientStartURLstringOptionalSpecifies 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]]`
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
faxNumberstringOptionalReserved for Docusign.
faxNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
firstNamestringOptionalThe recipient's first name.

Maximum Length: 50 characters.
firstNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
fullNamestringOptionalReserved for Docusign.
fullNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckConfigurationNamestringOptionalThe 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.
idCheckConfigurationNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckInformationInputModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item id Check Information Input
identityVerificationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item identity Verification
inheritEmailNotificationConfigurationstringOptionalWhen **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.
lastNamestringOptionalThe recipient's last name.
lastNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
lockedRecipientPhoneAuthEditablestringOptionalReserved for Docusign.
lockedRecipientSmsEditablestringOptionalReserved for Docusign.
namestringOptionalThe 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.
nameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
notestringOptionalA 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.
noteMetadataModelOptionalExpand Updates a template document — response body — name Metadata
phoneAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item phone Authentication
phoneNumberModelOptionalExpand Add envelope archive metadata — request body — body template Roles item phone Number
proofFileModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item proof File
recipientAttachmentsarrayOptionalReserved for Docusign.
recipientAttachments[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
recipientAuthenticationStatusModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
recipientFeatureMetadataarrayOptionalMetadata about the features that are supported for the recipient type. This property is read-only.
recipientFeatureMetadata[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
recipientIdstringOptionalA 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`.
recipientIdGuidstringOptionalThe 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.
recipientTypestringOptionalThe 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.
recipientTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireIdLookupstringOptionalWhen **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.
requireIdLookupMetadataModelOptionalExpand Updates a template document — response body — name Metadata
roleNamestringOptionalOptional element. Specifies the role name associated with the recipient.

This property is required when you are working with template recipients.
routingOrderstringOptionalSpecifies the routing order of the recipient in the envelope.
routingOrderMetadataModelOptionalExpand Updates a template document — response body — name Metadata
sentDateTimestringOptionalThe UTC DateTime when the envelope was sent. This property is read-only.
signedDateTimestringOptionalReserved for Docusign.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).
signingGroupIdMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupNamestringOptionalOptional. The name of the signing group.

Maximum Length: 100 characters.
signingGroupTypestringOptional
signingGroupUsersarrayOptionalA complex type that contains information about users in the signing group.
signingGroupUsers[]ModelEach itemExpand Add envelope archive metadata — request body — body sender
smsAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item sms Authentication
socialAuthenticationsarrayOptionalDeprecated.
socialAuthentications[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item social Authentications item
statusstringOptionalThe 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`.
statusCodestringOptionalThe code associated with the recipient's status. This property is read-only.
suppressEmailsstringOptionalWhen **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox.
templateLockedstringOptionalWhen **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients.
templateRequiredstringOptionalWhen **true,** the sender may not remove the recipient. Used only when working with template recipients.
totalTabCountstringOptionalThe total number of tabs in the documents. This property is read-only.
userIdstringOptionalThe 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.
webFormRecipientViewIdstringOptional

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 in Person Signers item

FieldTypePresenceDescription and constraints
$objectRootContains information about an in-person recipient. This is a Docusign user,
acting as a Signing Host,
who is in the same physical location as the signer.
To learn about the fields used
for the eNotary feature,
see the [EnvelopeRecipients resource](/docs/esign-rest-api/reference/envelopes/enveloperecipients/#in-person-signer-recipient).
accessCodestringOptionalIf 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.
accessCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
addAccessCodeToEmailstringOptionalOptional. 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.
allowSystemOverrideForLockedRecipientstringOptionalWhen **true,** if the recipient is locked on a template, advanced recipient routing can override the lock.
autoNavigationstringOptionalWhen **true,** autonavigation is set for the recipient.
autoRespondedReasonstringOptionalError 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.
bulkSendV2RecipientstringOptional
canSignOfflinestringOptionalWhen **true,** specifies that the signer can perform the signing ceremony offline.
clientUserIdstringOptionalSpecifies 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.
completedCountstringOptionalIndicates the number of times that the recipient has been through a signing completion.

If this number is greater than `0` for a signing group, only the user who previously completed may sign again.
creationReasonstringOptionalThe reason why the recipient was created (for example, `sender`). This property is read-only.
customFieldsarrayOptionalAn 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[]stringEach item
declinedDateTimestringOptionalThe date and time the recipient declined the document. This property is read-only.
declinedReasonstringOptionalThe reason the recipient declined the document. This property is read-only.
defaultRecipientstringOptionalWhen **true,**
this is the default recipient for the envelope.
This option is used when creating an envelope from a template.
deliveredDateTimestringOptionalThe date and time that the envelope was delivered to the recipient. This property is read-only.
deliveryMethodstringOptionalThe 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/)
deliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
designatorIdstringOptionalReserved for Docusign.
designatorIdGuidstringOptionalReserved for Docusign.
documentTemplateIdstringOptional
documentVisibilityarrayOptionalA 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[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item document Visibility item
emailstringOptionalThe signer's email address in an eNotary flow.

Use only when `inPersonSigningType` is `notary`.
For regular in-person-signer flow, use `signerEmail` instead.
emailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailNotificationModelOptionalExpand Add envelope archive metadata — request body — body template Roles item email Notification
embeddedRecipientStartURLstringOptionalSpecifies 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]]`
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
excludedDocumentsarrayOptionalSpecifies 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[]stringEach item
faxNumberstringOptionalReserved for Docusign.
faxNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
hostEmailstringOptionalThe email address of the signing host.
This is the Docusign user that is hosting the in-person signing session.

Required when `inPersonSigningType` is `inPersonSigner`.
For eNotary flow, use `email` instead.

Maximum Length: 100 characters.
hostEmailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
hostNamestringOptionalThe name of the signing host.
This is the Docusign user that is hosting the in-person signing session.

Required when `inPersonSigningType` is `inPersonSigner`.
For eNotary flow, use `name` instead.

Maximum Length: 100 characters.
hostNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckConfigurationNamestringOptionalThe 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.
idCheckConfigurationNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckInformationInputModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item id Check Information Input
identityVerificationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item identity Verification
inPersonSigningTypestringOptionalSpecifies whether the envelope uses the eNotary feature.
Valid values:

- `inPersonSigner`: The envelope uses the normal in-person signing flow.
- `notary`: The envelope uses the eNotary in-person signing flow.
inPersonSigningTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
inheritEmailNotificationConfigurationstringOptionalWhen **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.
lockedRecipientPhoneAuthEditablestringOptionalReserved for Docusign.
lockedRecipientSmsEditablestringOptionalReserved for Docusign.
namestringOptionalThe signer's full legal name in an eNotary flow.

Required when `inPersonSigningType` is `notary`.
For a regular in-person-signer flow, use `signerName` instead.

Maximum Length: 100 characters.
nameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
notaryHostModelOptionalExpand Add envelope archive metadata — request body — body recipients in Person Signers item notary Host
notaryIdstringOptional
notestringOptionalA note sent to the in-person signer in the signing email.
This note is visible only to this recipient.

Maximum Length: 1000 characters.
noteMetadataModelOptionalExpand Updates a template document — response body — name Metadata
offlineAttributesModelOptionalExpand Deletes recipients from a template — response body — signers item offline Attributes
phoneAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item phone Authentication
proofFileModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item proof File
recipientAttachmentsarrayOptionalReserved for Docusign.
recipientAttachments[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
recipientAuthenticationStatusModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
recipientFeatureMetadataarrayOptionalMetadata about the features that are supported for the recipient type. This property is read-only.
recipientFeatureMetadata[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
recipientIdstringOptionalA 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`.
recipientIdGuidstringOptionalThe 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.
recipientSignatureProvidersarrayOptionalThe 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[]ModelEach itemExpand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item
recipientSuppliesTabsstringOptionalWhen **true,** specifies that the recipient creates the tabs.
recipientTypestringOptionalThe 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.
recipientTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireIdLookupstringOptionalWhen **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.
requireIdLookupMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireSignOnPaperstringOptionalWhen **true,** the signer must print, sign, and upload or fax the signed documents to Docusign.
requireSignerCertificatestringOptionalBy 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.
requireUploadSignaturestringOptionalWhen **true,** the signer is required to upload a new signature, even if they have a pre-adopted signature in their personal Docusign account.
roleNamestringOptionalOptional element. Specifies the role name associated with the recipient.

This property is required when you are working with template recipients.
routingOrderstringOptionalSpecifies the routing order of the recipient in the envelope.
routingOrderMetadataModelOptionalExpand Updates a template document — response body — name Metadata
sentDateTimestringOptionalThe UTC DateTime when the envelope was sent. This property is read-only.
signInEachLocationstringOptionalWhen **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).
signInEachLocationMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signatureInfoModelOptionalExpand Add envelope archive metadata — request body — body recipients signers item signature Info
signedDateTimestringOptionalReserved for Docusign.
signerEmailstringOptionalThe in-person signer's email address.

Required when `inPersonSigningType` is `inPersonSigner`.
For eNotary flow, use `email` instead.

Maximum Length: 100 characters.
signerEmailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signerFirstNamestringOptionalThe signer's first name.
signerFirstNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signerLastNamestringOptionalThe signer's last name.
signerLastNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signerNamestringOptionalRequired. The full legal name of a signer for the envelope.

Maximum Length: 100 characters.


signerNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupIdstringOptionalNot applicable. You cannot use a signing group for an in-person signer.
signingGroupIdMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupNamestringOptionalNot applicable.
signingGroupTypestringOptional
signingGroupUsersarrayOptionalNot applicable.
signingGroupUsers[]ModelEach itemExpand Add envelope archive metadata — request body — body sender
smsAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item sms Authentication
socialAuthenticationsarrayOptionalDeprecated.
socialAuthentications[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item social Authentications item
statusstringOptionalThe 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`.
statusCodestringOptionalThe code associated with the recipient's status. This property is read-only.
suppressEmailsstringOptionalWhen **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox.
tabsModelOptionalExpand Add envelope archive metadata — request body — body documents item tabs
templateLockedstringOptionalWhen **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients.
templateRequiredstringOptionalWhen **true,** the sender may not remove the recipient. Used only when working with template recipients.
totalTabCountstringOptionalThe total number of tabs in the documents. This property is read-only.
userIdstringOptionalThe 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.
webFormRecipientViewIdstringOptional

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 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 in Person Signers item notary Host, 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 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 in Person Signers item notary Host

FieldTypePresenceDescription and constraints
$objectRootThis object is used only when `inPersonSigningType` in the `inPersonSigner` object is `notary`.

It describes information about the notary host.
The following information is required
when using the eNotary in-person signing flow:

* `name`: Specifies the notary's full legal name.
* `email`: Specifies the notary's email address.
* `recipientId`: A unique ID number for the notary signing host.
accessCodestringOptionalIf 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.
accessCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
addAccessCodeToEmailstringOptionalOptional. 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.
allowSystemOverrideForLockedRecipientstringOptionalWhen **true,** if the recipient is locked on a template, advanced recipient routing can override the lock.
autoRespondedReasonstringOptionalError 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.
bulkSendV2RecipientstringOptional
clientUserIdstringOptionalSpecifies 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.
completedCountstringOptionalIndicates 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.
customFieldsarrayOptionalAn 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[]stringEach item
declinedDateTimestringOptionalThe date and time the recipient declined the document. This property is read-only.
declinedReasonstringOptionalThe reason the recipient declined the document. This property is read-only.
deliveredDateTimestringOptionalThe date and time that the envelope was delivered to the recipient. This property is read-only.
deliveryMethodstringOptionalThe 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/)
deliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
designatorIdstringOptionalReserved for Docusign.
designatorIdGuidstringOptionalReserved for Docusign.
documentTemplateIdstringOptional
documentVisibilityarrayOptionalA 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[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item document Visibility item
emailstringOptionalThe notary's email address.

Maximum Length: 100 characters.
emailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailNotificationModelOptionalExpand Add envelope archive metadata — request body — body template Roles item email Notification
embeddedRecipientStartURLstringOptionalSpecifies 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]]`
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
faxNumberstringOptionalReserved for Docusign.
faxNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
hostRecipientIdstringOptionalThe host recipient ID.
idCheckConfigurationNamestringOptionalThe 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.
idCheckConfigurationNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckInformationInputModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item id Check Information Input
identityVerificationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item identity Verification
inheritEmailNotificationConfigurationstringOptionalWhen **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.
lockedRecipientPhoneAuthEditablestringOptionalReserved for Docusign.
lockedRecipientSmsEditablestringOptionalReserved for Docusign.
namestringOptionalThe notary's full legal name.

Maximum Length: 100 characters.
nameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
notestringOptionalA note sent to the notary in the signing email.
This note is visible only to this notary.

Maximum Length: 1000 characters.
noteMetadataModelOptionalExpand Updates a template document — response body — name Metadata
phoneAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item phone Authentication
proofFileModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item proof File
recipientAttachmentsarrayOptionalReserved for Docusign.
recipientAttachments[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
recipientAuthenticationStatusModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
recipientFeatureMetadataarrayOptionalMetadata about the features that are supported for the recipient type. This property is read-only.
recipientFeatureMetadata[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
recipientIdstringOptionalUnique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
recipientIdGuidstringOptionalThe 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.
recipientTypestringOptionalThe 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.
recipientTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireIdLookupstringOptionalWhen **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.
requireIdLookupMetadataModelOptionalExpand Updates a template document — response body — name Metadata
roleNamestringOptionalOptional element. Specifies the role name associated with the recipient.

This property is required when you are working with template recipients.
routingOrderstringOptionalSpecifies the routing order of the recipient in the envelope.
routingOrderMetadataModelOptionalExpand Updates a template document — response body — name Metadata
sentDateTimestringOptionalThe UTC DateTime when the envelope was sent. This property is read-only.
signedDateTimestringOptionalReserved for Docusign.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).
signingGroupIdMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupNamestringOptionalOptional. The name of the signing group.

Maximum Length: 100 characters.
signingGroupUsersarrayOptionalA complex type that contains information about users in the signing group.
signingGroupUsers[]ModelEach itemExpand Add envelope archive metadata — request body — body sender
smsAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item sms Authentication
socialAuthenticationsarrayOptionalDeprecated.
socialAuthentications[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item social Authentications item
statusstringOptionalThe 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`.
statusCodestringOptionalThe code associated with the recipient's status. This property is read-only.
suppressEmailsstringOptionalWhen **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox.
tabsModelOptionalExpand Add envelope archive metadata — request body — body documents item tabs
templateLockedstringOptionalWhen **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients.
templateRequiredstringOptionalWhen **true,** the sender may not remove the recipient. Used only when working with template recipients.
totalTabCountstringOptionalThe total number of tabs in the documents. This property is read-only.
userIdstringOptionalThe 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.
webFormRecipientViewIdstringOptional

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 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 intermediaries item

FieldTypePresenceDescription and constraints
$objectRootContains information about an intermediary recipient. An intermediary is a recipient who can, but is not required to, add name and email information for recipients at the same or subsequent level in the routing order, unless subsequent agents, editors or intermediaries are added.
accessCodestringOptionalIf 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.
accessCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
addAccessCodeToEmailstringOptionalOptional. 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.
additionalNotificationsarrayOptionalAn array of additional notification objects.
additionalNotifications[]ModelEach itemExpand Add envelope archive metadata — request body — body template Roles item additional Notifications item
allowSystemOverrideForLockedRecipientstringOptionalWhen **true,** if the recipient is locked on a template, advanced recipient routing can override the lock.
autoRespondedReasonstringOptionalError 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.
bulkSendV2RecipientstringOptional
clientUserIdstringOptionalSpecifies 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.
completedCountstringOptionalIndicates 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.
consentDetailsListarrayOptional
consentDetailsList[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients agents item consent Details List item
customFieldsarrayOptionalAn 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[]stringEach item
declinedDateTimestringOptionalThe date and time the recipient declined the document. This property is read-only.
declinedReasonstringOptionalThe reason the recipient declined the document. This property is read-only.
deliveredDateTimestringOptionalThe date and time that the envelope was delivered to the recipient. This property is read-only.
deliveryMethodstringOptionalThe 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/)
deliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
designatorIdstringOptionalReserved for Docusign.
designatorIdGuidstringOptionalReserved for Docusign.
documentTemplateIdstringOptional
documentVisibilityarrayOptionalA 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[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item document Visibility item
emailstringOptionalThe recipient's email address. Notification of the document to sign is sent to this email address.

Maximum length: 100 characters.
emailMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailNotificationModelOptionalExpand Add envelope archive metadata — request body — body template Roles item email Notification
emailRecipientPostSigningURLstringOptional
embeddedRecipientStartURLstringOptionalSpecifies 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]]`
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
excludedDocumentsarrayOptionalSpecifies 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[]stringEach item
faxNumberstringOptionalReserved for Docusign.
faxNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
firstNamestringOptionalThe recipient's first name. Maximum Length: 50 characters.
firstNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
fullNamestringOptionalReserved for Docusign.
fullNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckConfigurationNamestringOptionalThe 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.
idCheckConfigurationNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
idCheckInformationInputModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item id Check Information Input
identityVerificationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item identity Verification
inheritEmailNotificationConfigurationstringOptionalWhen **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.
lastNamestringOptionalThe recipient's last name.
lastNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
lockedRecipientPhoneAuthEditablestringOptionalReserved for Docusign.
lockedRecipientSmsEditablestringOptionalReserved for Docusign.
namestringOptionalThe 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.
nameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
notestringOptionalA 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.
noteMetadataModelOptionalExpand Updates a template document — response body — name Metadata
phoneAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item phone Authentication
phoneNumberModelOptionalExpand Add envelope archive metadata — request body — body template Roles item phone Number
proofFileModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item proof File
recipientAttachmentsarrayOptionalReserved for Docusign.
recipientAttachments[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Attachments item
recipientAuthenticationStatusModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status
recipientFeatureMetadataarrayOptionalMetadata about the features that are supported for the recipient type. This property is read-only.
recipientFeatureMetadata[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item
recipientIdstringOptionalA 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`.
recipientIdGuidstringOptionalThe 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.
recipientTypestringOptionalThe 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.
recipientTypeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
requireIdLookupstringOptionalWhen **true,** the recipient is required to use the specified ID check method (including Phone and SMS authentication) to validate their identity.
requireIdLookupMetadataModelOptionalExpand Updates a template document — response body — name Metadata
roleNamestringOptionalOptional element. Specifies the role name associated with the recipient.

This property is required when you are working with template recipients.
routingOrderstringOptionalSpecifies the routing order of the recipient in the envelope.
routingOrderMetadataModelOptionalExpand Updates a template document — response body — name Metadata
sentDateTimestringOptionalThe UTC DateTime when the envelope was sent. This property is read-only.
signedDateTimestringOptionalReserved for Docusign.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).
signingGroupIdMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signingGroupNamestringOptionalOptional. The name of the signing group.

Maximum Length: 100 characters.
signingGroupTypestringOptional
signingGroupUsersarrayOptionalA complex type that contains information about users in the signing group.
signingGroupUsers[]ModelEach itemExpand Add envelope archive metadata — request body — body sender
smsAuthenticationModelOptionalExpand Add envelope archive metadata — request body — body recipients seals item sms Authentication
socialAuthenticationsarrayOptionalDeprecated.
socialAuthentications[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients seals item social Authentications item
statusstringOptionalThe 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`.
statusCodestringOptionalThe code associated with the recipient's status. This property is read-only.
suppressEmailsstringOptionalWhen **true,** email notifications are suppressed for the recipient, and they must access envelopes and documents from their Docusign inbox.
templateLockedstringOptionalWhen **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients.
templateRequiredstringOptionalWhen **true,** the sender may not remove the recipient. Used only when working with template recipients.
totalTabCountstringOptionalThe total number of tabs in the documents. This property is read-only.
userIdstringOptionalThe 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.
webFormRecipientViewIdstringOptional

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

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.