Skip to content

DocuSign: Esignature schemas (part 12)

41 DocuSign schemas with complete fields and constraints.

← Esignature operations · All schemas

Add envelope archive metadata — request body — body recipients witnesses item

FieldTypePresenceDescription and constraints
$objectRootA complex type containing information about a witness recipient. Witnesses are recipients whose signatures affirm that the identified signers have signed the documents in the envelope.
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.
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.
bulkRecipientsUristringOptionalReserved for Docusign.
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 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
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 recipient is the default recipient and any tabs generated by the transformPdfFields option are mapped to this recipient.
delegatedByModelOptionalExpand Add envelope archive metadata — request body — body recipients signers item delegated By
delegatedToarrayOptional
delegatedTo[]ModelEach itemExpand Add envelope archive metadata — request body — body recipients signers item delegated By
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.
isBulkRecipientstringOptionalReserved for Docusign.
isBulkRecipientMetadataModelOptionalExpand Updates a template document — response body — name Metadata
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
notaryIdstringOptional
notarySignerEmailSentstringOptional
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
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
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
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.
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.
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.
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
witnessForstringOptionalThe `recipientId` of the person or party for whom the recipient is a witness.
witnessForGuidstringOptionalNot used. Use the `witnessFor` property instead.

Referenced models: Deletes recipients from a template — response body — signers item offline Attributes, Updates a template document — response body — name Metadata, Add envelope archive metadata — response body — error Details, Add envelope archive metadata — request body — body recipients seals item recipient Authentication Status, Add envelope archive metadata — request body — body recipients agents item consent Details List item, Add envelope archive metadata — request body — body recipients signers item delegated By, Add envelope archive metadata — request body — body recipients seals item document Visibility item, Add envelope archive metadata — request body — body recipients seals item recipient Feature Metadata item, Add envelope archive metadata — request body — body recipients seals item id Check Information Input, Add envelope archive metadata — request body — body template Roles item additional Notifications item, Add envelope archive metadata — request body — body recipients seals item recipient Attachments item, Add envelope archive metadata — request body — body template Roles item email Notification, Add envelope archive metadata — request body — body recipients seals item identity Verification, Add envelope archive metadata — request body — body recipients seals item phone Authentication, Add envelope archive metadata — request body — body template Roles item phone Number, Add envelope archive metadata — request body — body recipients seals item proof File, Add envelope archive metadata — request body — body recipients seals item sms Authentication, Add envelope archive metadata — request body — body recipients signers item signature Info, Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item, Add envelope archive metadata — request body — body recipients seals item social Authentications item, Add envelope archive metadata — request body — body documents item tabs, Add envelope archive metadata — request body — body sender

Add envelope archive metadata — request body — body sender

FieldTypePresenceDescription and constraints
$objectRoot
accountIdstringOptionalThe account ID associated with the envelope.
accountNamestringOptionalThe name on the account.
activationAccessCodestringOptionalAccess code provided to the user to activate the account.
emailstringOptionalThe user's email address.
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
ipAddressstringOptional
loginStatusstringOptionalWhen **true,** indicates that the user is logged in. This is a read-only property.
membershipIdstringOptionalThe user's membership ID.
sendActivationEmailstringOptionalThis field is no longer supported for most accounts. To create an eSignature user without sending an activation email, use the Admin API by following [these steps](/docs/admin-api/how-to/create-active-user/).
uristringOptionalA URI containing the user ID.
userIdstringOptionalThe ID of the user to access.
userNamestringOptionalThe name of the user.
userStatusstringOptionalStatus of the user's account. One of:

- `ActivationRequired`
- `ActivationSent`
- `Active`
- `Closed`
- `Disabled`
userTypestringOptionalThe type of user, for example `CompanyUser`.

Referenced models: Add envelope archive metadata — response body — error Details

Add envelope archive metadata — request body — body template Roles item

FieldTypePresenceDescription and constraints
$objectRootInformation about a specific role.
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.
additionalNotificationsarrayOptionalAn array of additional notification objects.
additionalNotifications[]ModelEach itemExpand Add envelope archive metadata — request body — body template Roles item additional Notifications item
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.
defaultRecipientstringOptionalWhen **true,** this recipient is the default recipient and any tabs generated by the `transformPdfFields` option are mapped to this recipient.
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/)
emailstringOptionalThe email address of the person associated with a role name. It is the email address of the person specified in the `name` property.

For an in-person signer, this is the email address of the host.
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]]`
inPersonSignerNamestringOptionalThe full legal name of the in-person signer.

Maximum Length: 100 characters.
namestringOptionalSpecifies the recipient's name.

For an in-person signer, this is the name of the host.
phoneNumberModelOptionalExpand Add envelope archive metadata — request body — body template Roles item phone Number
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
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.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).
signingGroupNamestringOptionalThe display name for 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
tabsModelOptionalExpand Add envelope archive metadata — request body — body documents item tabs

Referenced models: Add envelope archive metadata — request body — body template Roles item additional Notifications item, Add envelope archive metadata — request body — body template Roles item email Notification, Add envelope archive metadata — request body — body template Roles item phone Number, Add envelope archive metadata — request body — body template Roles item recipient Signature Providers 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 template Roles item additional Notifications item

FieldTypePresenceDescription and constraints
$objectRootDescribes an additional notification method.
phoneNumberModelOptionalExpand Add envelope archive metadata — request body — body template Roles item phone Number
secondaryDeliveryMethodstringOptionalThe secondary 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/)
secondaryDeliveryMethodMetadataModelOptionalExpand Updates a template document — response body — name Metadata
secondaryDeliveryStatusstringOptionalThe status of the delivery. This property is read-only.

One of:

- `autoresponded`
- `optedout`
- `limitreached`

Referenced models: Updates a template document — response body — name Metadata, Add envelope archive metadata — request body — body template Roles item phone Number

Add envelope archive metadata — request body — body template Roles item email Notification

FieldTypePresenceDescription and constraints
$objectRootSets custom email subject and email body for individual
recipients. **Note:** You must explicitly set `supportedLanguage`
if you use this feature.
emailBodystringOptionalThe body of the email message.
emailBodyMetadataModelOptionalExpand Updates a template document — response body — name Metadata
emailSubjectstringOptionalThe subject line for the email notification.
emailSubjectMetadataModelOptionalExpand Updates a template document — response body — name Metadata
supportedLanguagestringOptionalThe language to use for the standard email format and signing view for a recipient.

For example, this setting determines the language of the recipient's email notification message. It also determines the language used for buttons and tabs in both the email notification and the signing experience.

**Note:** This setting affects only Docusign standard text. Any custom text that you enter for the `emailBody` and `emailSubject` of the notification is not translated, and appears exactly as you enter it.

To retrieve the possible values, use the [Accounts::listSupportedLanguages](/docs/esign-rest-api/reference/accounts/accounts/listsupportedlanguages/) method.
supportedLanguageMetadataModelOptionalExpand Updates a template document — response body — name Metadata

Referenced models: Updates a template document — response body — name Metadata

Add envelope archive metadata — request body — body template Roles item phone Number

FieldTypePresenceDescription and constraints
$objectRootDescribes the recipient phone number.
countryCodestringOptionalThe numeric country calling code for `number`. For example, the country calling code for the US and Canada is `1`, for the UK: `44`,

Do not include the `+` symbol.
countryCodeMetadataModelOptionalExpand Updates a template document — response body — name Metadata
numberstringOptionalThe telephone number. Use only the digits `0`-`9`. Remove any non-numeric characters.

Do not include the `countryCode`. For US, Canada, and other
[North American Numbering Plan](https://en.wikipedia.org/wiki/North_American_Numbering_Plan) countries, do not include a leading `1` or `0`.
numberMetadataModelOptionalExpand Updates a template document — response body — name Metadata

Referenced models: Updates a template document — response body — name Metadata

Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item

FieldTypePresenceDescription and constraints
$objectRootAn Electronic or Standards Based Signature (digital signature) provider for the signer to use. [More information](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/).
sealDocumentsWithTabsOnlystringOptionalBy default, electronic seals apply on all documents in an envelope. If any of the documents has a `signHere` tab, then a visual representation of the electronic seal will show up in the final document. If not, the electronic seal will be visible in the metadata but not in the content of the document.

To apply electronic seals on specific documents only, you must enable the `sealDocumentsWithTabsOnly` parameter. In this case, Electronic Seal applies only on documents that have `signHere` tabs set for the Electronic Seal recipient. Other documents won't be sealed.

If using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand/) feature, set this value to `false` for the notary recipient, and set it to `false` or omit it for the signer recipient.
sealNamestringOptionalIndicates the name of the electronic seal to apply on documents.
signatureProviderNamestringOptionalThe name of an Electronic or Standards Based Signature (digital signature) provider for the signer to use. For details, see [the current provider list](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/). You can also retrieve the list by using the [AccountSignatureProviders: List](/docs/esign-rest-api/reference/accounts/accountsignatureproviders/list/) method.

Example: `universalsignaturepen_default`

If using the [Notary On-Demand](/docs/notary-api/notary101/notary-on-demand/) feature, set this value to `ds_authority_idv` for the notary recipient, and set it to `universalsignaturepen_imageonly` or omit it for the signer recipient.
signatureProviderNameMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signatureProviderOptionsModelOptionalExpand Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item signature Provider Options

Referenced models: Updates a template document — response body — name Metadata, Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item signature Provider Options

Add envelope archive metadata — request body — body template Roles item recipient Signature Providers item signature Provider Options

FieldTypePresenceDescription and constraints
$objectRootOption settings for the signature provider. Different providers require or use different options. [The current provider list and the options they require.](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/)
cpfNumberstringOptionalReserved for Docusign.
cpfNumberMetadataModelOptionalExpand Updates a template document — response body — name Metadata
oneTimePasswordstringOptionalA pre-shared secret that the signer must enter to complete the signing process. Eg last six digits of the signer's government ID or Social Security number. Or a newly created pre-shared secret for the transaction. Note: some signature providers may require an exact (case-sensitive) match if alphabetic characters are included in the field.
oneTimePasswordMetadataModelOptionalExpand Updates a template document — response body — name Metadata
signerRolestringOptionalThe role or capacity of the signing recipient. Examples: Manager, Approver, etc.
signerRoleMetadataModelOptionalExpand Updates a template document — response body — name Metadata
smsstringOptionalThe mobile phone number used to send the recipient an access code for the signing ceremony. Format: a string starting with +, then the country code followed by the full mobile phone number without any spaces or special characters. Omit leading zeroes before a city code. Examples: +14155551234, +97235551234, +33505551234.
smsMetadataModelOptionalExpand Updates a template document — response body — name Metadata

Referenced models: Updates a template document — response body — name Metadata

Add envelope archive metadata — request body — body workflow

FieldTypePresenceDescription and constraints
$objectRootDescribes the workflow for an envelope.
currentWorkflowStepIdstringOptionalThe `workflowStepId` of the current step.
This is not an index into the `workflowSteps` array in this object.
See the `workflowStep` object.
overwriteUpdateModestringOptional
resumeDatestringOptionalThe ISO 8601 timestamp of when the envelope is scheduled to be sent, if applicable. Its value is the maximum of the `resumeDate` property on `scheduledSending` and the `resumeDate` property on the current `workflowStep`.

This property is read-only.
scheduledSendingModelOptionalExpand Add envelope archive metadata — request body — body workflow scheduled Sending
workflowStatusstringOptionalThe status of the workflow:

- `paused` if the workflow is paused
- `in_progress` if the workflow is in progress
workflowStepsarrayOptionalAn array of workflow steps.
workflowSteps[]ModelEach itemExpand Add envelope archive metadata — request body — body workflow workflow Steps item

Referenced models: Add envelope archive metadata — request body — body workflow scheduled Sending, Add envelope archive metadata — request body — body workflow workflow Steps item

Add envelope archive metadata — request body — body workflow scheduled Sending

FieldTypePresenceDescription and constraints
$objectRootA complex element that specifies the scheduled sending settings for the envelope.
bulkListIdstringOptionalThe ID of the bulk list. Set this optional value to use scheduled sending with a bulk send operation.
resumeDatestringOptionalThe timestamp of when the envelope is scheduled to be sent in ISO 8601 format.

This property is read-only.
rulesarrayOptionalUser-specified rules indicating how and when the envelope should be scheduled for sending. Only one rule may be specified.
rules[]ModelEach itemExpand Updates the scheduled sending rules for an envelope's workflow — response body — rules item
statusstringOptionalStatus of the scheduled sending job. Valid values:

- `pending`: The envelope has not yet been sent and the scheduled sending delay has not been initiated.
- `started`: The sender has initiated the sending process. The delay has not elapsed, so the envelope has not yet been sent to the first recipient.
- `completed`: The delay has elapsed and the envelope has been sent to the first recipient.

This property is read-only.

Referenced models: Updates the scheduled sending rules for an envelope's workflow — response body — rules item

Add envelope archive metadata — request body — body workflow workflow Steps item

FieldTypePresenceDescription and constraints
$objectRootDescribes a single step in a workflow.
actionstringOptionalIndicates the action to perform. Valid values:

- `pause_before`: The workflow should pause before the trigger described by `triggerOnItem` is reached.
completedDatestringOptionalThe timestamp of when the workflow step transitioned to `completed` status.

This property is read-only.
delayedRoutingModelOptionalExpand Add envelope archive metadata — request body — body workflow workflow Steps item delayed Routing
itemIdstringOptionalThe unique ID of the item being triggered.
recipientRoutingModelOptionalExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing
statusstringOptionalThe status of the step. Valid values:

- `inactive`
- `in_progress`
- `paused`
- `pending`
- `completed`

This property is read-only.
triggerOnItemstringOptionalThe type of item that triggers this workflow step. Valid values:

- `routing_order`
triggeredDatestringOptionalThe timestamp of when the workflow step transitioned to `in_progress` status.

This property is read-only.
workflowStepIdstringOptionalA unique identifier for this workflow step.

This property is read-only.

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item delayed Routing, Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing

Add envelope archive metadata — request body — body workflow workflow Steps item delayed Routing

FieldTypePresenceDescription and constraints
$objectRootA complex element that specifies the delayed routing settings for the workflow step.
resumeDatestringOptionalThe ISO 8601 timestamp of when the envelope is scheduled to be sent to the recipients associated with the workflow step. This property is `null` if the workflow step has not been initiated.

This property is read-only.
rulesarrayOptionalUser-specified rules indicating how and when the envelope should sent for the workflow step and its associated recipients. Only one rule may be specified.
rules[]ModelEach itemExpand Updates the scheduled sending rules for an envelope's workflow — response body — rules item
statusstringOptionalStatus of the delayed routing step. Valid values:

- `pending`: The workflow step has not been reached and the delay has not been initiated.
- `started`: The workflow step has begun and the delay is in progress. The envelope has not yet been sent to the workflow step's recipients.
- `completed`: The delay has elapsed and the envelope has been sent to the workflow step's recipients.

This property is read-only.

Referenced models: Updates the scheduled sending rules for an envelope's workflow — response body — rules item

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing

FieldTypePresenceDescription and constraints
$objectRootDescribes the recipient routing rules.
rulesModelOptionalExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules

FieldTypePresenceDescription and constraints
$objectRoot
conditionalRecipientsarrayOptional
conditionalRecipients[]ModelEach itemExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item

FieldTypePresenceDescription and constraints
$objectRootA rule that defines a set of recipients and the conditions under which they will be used for the envelope.
conditionsarrayOptionalAn array of conditions that define when the recipients will be used.
conditions[]ModelEach itemExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item
orderstringOptionalAn integer that specifies the order in which rules are processed.
Lower values are processed before higher values.
recipientGroupModelOptionalExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group
recipientIdstringOptionalThe ID of the recipient to whom the condition will be applied. This value should match the `recipientId` defined in the recipient object.

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item, Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item

FieldTypePresenceDescription and constraints
$objectRoot
filtersarrayOptional
filters[]ModelEach itemExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item filters item
orderstringOptionalAn integer that specifies the order in which rules are processed.
Lower values are processed before higher values.
recipientLabelstringOptionalAn identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item filters item

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item conditions item filters item

FieldTypePresenceDescription and constraints
$objectRoot
operatorstringOptionalHow the tab value is compared to the `value` property. Valid values:

- `equals`
- `greaterThan`
- `greaterThanEquals`
- `lessThan`
- `lessThanEquals`
- `filled`
- `selected`
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`.
scopestringOptionalThe scope under which the condition is evaluated. Valid values:

- `tabs`
tabIdstringOptionalThe unique identifier for the tab.
tabLabelstringOptionalThe label associated with the tab. This value may be an empty string.
If no value is provided, the tab type is used as the value.

Maximum Length: 500 characters.
tabTypestringOptionalIndicates the type of tab (for example, `signHere` or `initialHere`).
valuestringOptionalA set value to which the tab's actual value is compared.

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group

FieldTypePresenceDescription and constraints
$objectRootDescribes a group of recipients.
groupMessagestringOptionalThe group message, typically a description of the group.
groupNamestringOptionalThe name of the group.
recipientsarrayOptionalAn array of recipient objects that provides details about the recipients of the envelope.
recipients[]ModelEach itemExpand Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group recipients item

Referenced models: Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group recipients item

Add envelope archive metadata — request body — body workflow workflow Steps item recipient Routing rules conditional Recipients item recipient Group recipients item

FieldTypePresenceDescription and constraints
$objectRootDescribes a recipient who is a member of a conditional group.
emailstringOptionalThe email ID of the agent. This property is required. Maximum length: 100 characters.
namestringOptionalThe full legal name of the recipient. Maximum length: 100 characters.
recipientLabelstringOptionalAn identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).
roleNamestringOptionalSpecifies the signing group role of the recipient. This property is required.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).

Add envelope archive metadata — response body

FieldTypePresenceDescription and constraints
$objectRootThis object describes an envelope.
bulkEnvelopeStatusModelOptionalExpand Add envelope archive metadata — response body — bulk Envelope Status
envelopeIdstringOptionalThe envelope ID of the envelope status that failed to post.
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
recipientSigningUristringOptional
recipientSigningUriErrorstringOptional
statusstringOptionalIndicates the envelope status. Valid values are:

- `completed`: The recipients have finished working with the envelope: the documents are signed and all required tabs are filled in.
- `created`: The envelope is created as a draft. It can be modified and sent later.
- `declined`: The envelope has been declined by the recipients.
- `delivered`: The envelope has been delivered to the recipients.
- `sent`: The envelope will be sent to the recipients after the envelope is created.
- `signed`: The envelope has been signed by the recipients.
- `voided`: The envelope is no longer valid and recipients cannot access or sign the envelope.
statusDateTimestringOptionalThe DateTime that the envelope changed status (i.e. was created or sent.)
uristringOptionalA URI containing the user ID.

Referenced models: Add envelope archive metadata — response body — bulk Envelope Status, Add envelope archive metadata — response body — error Details

Add envelope archive metadata — response body — bulk Envelope Status

FieldTypePresenceDescription and constraints
$objectRoot
batchIdstringOptionalSpecifies an identifier which can be used to retrieve a more detailed status of individual bulk recipient batches.
batchSizestringOptionalThe number of items returned in this response.
bulkEnvelopesarrayOptionalA list of bulk envelope objects.
bulkEnvelopes[]ModelEach itemExpand Add envelope archive metadata — response body — bulk Envelope Status bulk Envelopes item
bulkEnvelopesBatchUristringOptionalURI at which you can retrieve the batch envelopes.
endPositionstringOptionalThe last index position in the result set.
failedstringOptionalThe number of entries with a status of failed.
nextUristringOptionalThe URI for the next chunk of records based on the search request. It is `null` if this is the last set of results for the search.
previousUristringOptionalThe URI for the prior chunk of records based on the search request. It is `null` if this is the first set of results for the search.
queuedstringOptionalThe number of entries with a status of queued.
resultSetSizestringOptionalThe number of results in this response. Because you can filter which entries are included in the response, this value is always less than or equal to the `totalSetSize`.
sentstringOptionalThe number of entries with a status of sent.
startPositionstringOptionalThe starting index position of the current result set.
submittedDatestringOptionalThe date on which the bulk envelope was created.
totalSetSizestringOptionalThe total number of items in the result set. This value is always greater than or equal to the value of `resultSetSize`.

Referenced models: Add envelope archive metadata — response body — bulk Envelope Status bulk Envelopes item

Add envelope archive metadata — response body — bulk Envelope Status bulk Envelopes item

FieldTypePresenceDescription and constraints
$objectRoot
bulkRecipientRowstringOptionalThe row of the recipient in the CSV file used to create the bulk recipient list.
bulkStatusstringOptionalIndicates the status of the bulk send operation. Returned values can be:
* queued
* processing
* sent
* failed
emailstringOptionalThe email address of the recipient assigned to this envelope transaction.
envelopeIdstringOptionalGUID of the bulk envelope.
envelopeUristringOptionalThe URI for retrieving the envelope or envelopes.
errorDetailsModelOptionalExpand Add envelope archive metadata — response body — error Details
namestringOptionalThe name of the recipient assigned to this envelope transaction.
submittedDateTimestringOptionalThe date and time on which the bulk envelope was created.
transactionIdstringOptionalIdentifier for the envelope transaction. The ID is a sender-generated value and is valid in the Docusign system for 7 days. Docusign recommends that you use a transaction ID for offline signing to ensure that an envelope is not sent multiple times. You can use the transaction ID to determine an envelope's status (queued, processing, sent, or failed) in cases where the Internet connection is lost before envelope status is returned.

Referenced models: Add envelope archive metadata — response body — error Details

Add envelope archive metadata — response body — error Details

FieldTypePresenceDescription and constraints
$objectRootThis object describes errors that occur. It is only valid for responses, and ignored in requests.
errorCodestringOptionalThe code associated with the error condition.
messagestringOptionalA brief message describing the error condition.

Adds a new step to a template's workflow — response body

FieldTypePresenceDescription and constraints
$objectRootDescribes a single step in a workflow.
actionstringOptionalIndicates the action to perform. Valid values:

- `pause_before`: The workflow should pause before the trigger described by `triggerOnItem` is reached.
completedDatestringOptionalThe timestamp of when the workflow step transitioned to `completed` status.

This property is read-only.
delayedRoutingModelOptionalExpand Updates the delayed routing rules for a template's workflow step — response body
A complex element that specifies the delayed routing settings for the workflow step.
itemIdstringOptionalThe unique ID of the item being triggered.
recipientRoutingModelOptionalExpand Adds a new step to a template's workflow — response body — recipient Routing
The rules for recipient routing.
statusstringOptionalThe status of the step. Valid values:

- `inactive`
- `in_progress`
- `paused`
- `pending`
- `completed`

This property is read-only.
triggerOnItemstringOptionalThe type of item that triggers this workflow step. Valid values:

* `routing_order`
triggeredDatestringOptionalThe timestamp of when the workflow step transitioned to `in_progress` status.

This property is read-only.
workflowStepIdstringOptionalA unique identifier for this workflow step.

This property is read-only.

Referenced models: Updates the delayed routing rules for a template's workflow step — response body, Adds a new step to a template's workflow — response body — recipient Routing

Adds a new step to a template's workflow — response body — recipient Routing

FieldTypePresenceDescription and constraints
$objectRootDescribes the recipient routing rules.
rulesModelOptionalExpand Adds a new step to a template's workflow — response body — recipient Routing rules
The recipient routing rules.

Referenced models: Adds a new step to a template's workflow — response body — recipient Routing rules

Adds a new step to a template's workflow — response body — recipient Routing rules

FieldTypePresenceDescription and constraints
$objectRoot
conditionalRecipientsarrayOptional
conditionalRecipients[]ModelEach itemExpand Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item

Referenced models: Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item

Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item

FieldTypePresenceDescription and constraints
$objectRootA rule that defines a set of recipients and the conditions under which they will be used for the envelope.
conditionsarrayOptionalAn array of conditions that define when the recipients will be used.
conditions[]ModelEach itemExpand Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item
orderstringOptionalAn integer that specifies the order in which rules are processed.
Lower values are processed before higher values.
recipientGroupModelOptionalExpand Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group
A set of recipients that may be used for the envelope, depending on the `conditions` defined.
recipientIdstringOptionalThe ID of the recipient to whom the condition will be applied. This value should match the `recipientId` defined in the recipient object.

Referenced models: Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item, Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group

Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item

FieldTypePresenceDescription and constraints
$objectRoot
filtersarrayOptional
filters[]ModelEach itemExpand Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item filters item
orderstringOptionalAn integer that specifies the order in which rules are processed.
Lower values are processed before higher values.
recipientLabelstringOptionalAn identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).

Referenced models: Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item filters item

Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item conditions item filters item

FieldTypePresenceDescription and constraints
$objectRoot
operatorstringOptionalHow the tab value is compared to the `value` property. Valid values:

* `equals`
* `greaterThan`
* `greaterThanEquals`
* `lessThan`
* `lessThanEquals`
* `filled`
* `selected`
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`.
scopestringOptionalThe scope under which the condition is evaluated. Valid values:

* `tabs`
tabIdstringOptionalThe unique identifier for the tab.
tabLabelstringOptionalThe label associated with the tab. This value may be an empty string.
If no value is provided, the tab type is used as the value.

Maximum Length: 500 characters.
tabTypestringOptionalIndicates the type of tab (for example, `signHere` or `initialHere`).
valuestringOptionalA set value to which the tab's actual value is compared.

Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group

FieldTypePresenceDescription and constraints
$objectRootDescribes a group of recipients.
groupMessagestringOptionalThe group message, typically a description of the group.
groupNamestringOptionalThe name of the group.
recipientsarrayOptionalAn array of recipient objects that provides details about the recipients of the envelope.
recipients[]ModelEach itemExpand Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group recipients item

Referenced models: Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group recipients item

Adds a new step to a template's workflow — response body — recipient Routing rules conditional Recipients item recipient Group recipients item

FieldTypePresenceDescription and constraints
$objectRootDescribes a recipient who is a member of a conditional group.
emailstringOptionalThe email ID of the agent. This property is required. Maximum length: 100 characters.
namestringOptionalThe full legal name of the recipient. Maximum length: 100 characters.
recipientLabelstringOptionalAn identifier for the recipient. After assigning this value in a `recipient` object, you can reference it in the `conditions` object to set the recipient as a conditional recipient. For an example, see [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients/).
roleNamestringOptionalSpecifies the signing group role of the recipient. This property is required.
signingGroupIdstringOptionalThe ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html).

Adds an existing brand to a group — request body — body

FieldTypePresenceDescription and constraints
$objectRootDetails about one or more brands.
brandsarrayOptionalA list of brands.
brands[]ModelEach itemExpand Adds an existing brand to a group — request body — body brands item

Referenced models: Adds an existing brand to a group — request body — body brands item

Adds an existing brand to a group — request body — body brands item

FieldTypePresenceDescription and constraints
$objectRootThis request object contains information about a specific brand.
brandIdstringOptionalThe ID of the brand used in API calls

Adds an existing brand to a group — response body

FieldTypePresenceDescription and constraints
$objectRootIf your account includes multiple signing brands, you can use the groups functionality to assign different brands to different groups. This resource enables you to manage group brands.
brandOptionsarrayOptionalA list of brands.
brandOptions[]ModelEach itemExpand Updates an existing brand — response body
recipientBrandIdDefaultstringOptionalThe brand that envelope recipients see when a brand is not explicitly set.
senderBrandIdDefaultstringOptionalThe brand that envelope senders see when a brand is not explicitly set.

Referenced models: Updates an existing brand — response body

Adds email setting overrides to an envelope — response body

FieldTypePresenceDescription and constraints
$objectRootA complex element that allows the sender to override some envelope email setting information. This can be used to override the Reply To email address and name associated with the envelope and to override the BCC email addresses to which an envelope is sent.

When the emailSettings information is used for an envelope, it only applies to that envelope.

**IMPORTANT:** The emailSettings information is not returned in the GET for envelope status. Use GET /email_settings to return information about the emailSettings.

EmailSettings consists of:

* replyEmailAddressOverride - The Reply To email used for the envelope. Docusign will verify that a correct email format is used, but does not verify that the email is active. Maximum Length: 100 characters.
* replyEmailNameOverride - The name associated with the Reply To email address. Maximum Length: 100 characters.
* bccEmailAddresses - An array of up to five email addresses to which the envelope is sent to as a BCC email. Only users with canManageAccount setting set to true can use this option.
Docusign verifies that the email format is correct, but does not verify that the email is active. Using this overrides the BCC for Email Archive information setting for this envelope. Maximum Length: 100 characters.
*Example*: if your account has BCC for Email Archive set up for the email address 'archive@example.com' and you send an envelope using the BCC Email Override to send a BCC email to 'salesarchive@example.com', then a copy of the envelope is only sent to the 'salesarchive@example.com' email address.
bccEmailAddressesarrayOptionalAn array containing the email address that should receive a copy of all email communications related to an envelope for archiving purposes. Maximum Length: 100 characters.

While this property is an array, note that it takes only a single email address.

**Note:** Only users with the `canManageAccount` setting set to **true** can use this option.

Docusign verifies that the email format is correct, but does not verify that the email address is active. You can use this for archiving purposes. However, using this property overrides the BCC for Email Archive information setting for this envelope.

**Example:** if your account has BCC for Email Archive set up for the email address archive@example.com and you send an envelope using the BCC Email Override to send a BCC email to salesarchive@example.com, then a copy of the envelope is only sent to the salesarchive@example.com email address.
bccEmailAddresses[]ModelEach itemExpand Adds email setting overrides to an envelope — response body — bcc Email Addresses item
replyEmailAddressOverridestringOptionalThe Reply To email address to use for email replies, instead of the one that is configured at the account level. Docusign verifies that the email address is in a correct format, but does not verify that it is active. Maximum Length: 100 characters.
replyEmailNameOverridestringOptionalThe name to associate with the Reply To email address, instead of the name that is configured at the account level. Maximum Length: 100 characters.

Referenced models: Adds email setting overrides to an envelope — response body — bcc Email Addresses item

Adds email setting overrides to an envelope — response body — bcc Email Addresses item

FieldTypePresenceDescription and constraints
$objectRootContains information about the BCC email address.
bccEmailAddressIdstringOptionalOnly users with canManageAccount setting can use this option. An array of up to 5 email addresses the envelope is sent to as a BCC email.

Example: If your account has BCC for Email Archive set up for the email address 'archive@example.com' and you send an envelope using the BCC Email Override to send a BCC email to 'salesarchive@example.com', then a copy of the envelope is only sent to the 'salesarchive@example.com' email address.
emailstringOptionalSpecifies the BCC email address. Docusign verifies that the email format is correct, but does not verify that the email is active.Using this overrides the BCC for Email Archive information setting for this envelope.

Maximum of length: 100 characters.

Adds members to a signing group — response body

FieldTypePresenceDescription and constraints
$objectRoot
usersarrayOptionalUser management information.
users[]ModelEach itemExpand Updates a signing group — response body — users item

Referenced models: Updates a signing group — response body — users item

Adds tabs for a recipient — esignature esignature Recipients Post Recipient Tabs — request body — body

FieldTypePresenceDescription and constraints
$objectRootAll of the tabs associated with a recipient. Each property is a list of a type of tab.
approveTabsarrayOptionalA list of
[Approve tabs][approve].

An Approve tab enables
the recipient to approve documents without
placing a signature or initials on the document. If the
recipient clicks the tab during the signing process, the
recipient is considered to have signed the document. No
information is shown on the document of the approval, but it
is recorded as a signature in the envelope history.
The value of an approve tab can't be set.

[approve]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
approveTabs[]ModelEach itemExpand Returns tabs on a template — response body — approve Tabs item
checkboxTabsarrayOptionalA list of
[Checkbox tabs][checkbox].


A Checkbox tab enables the recipient to select a yes/no (on/off) option. This value can be set.


[checkbox]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
checkboxTabs[]ModelEach itemExpand Returns tabs on a template — response body — checkbox Tabs item
commentThreadTabsarrayOptionalAn array of tabs that represents a collection of comments in a comment thread. For example, if a recipient has questions about the content of a document, they can add a comment to the document and control who else can see the comment. This value can't be set.
commentThreadTabs[]ModelEach itemExpand Returns tabs on a template — response body — comment Thread Tabs item
commissionCountyTabsarrayOptionalA list of
[Commission County tabs][cc].


A Commission County tab displays the county of a notary's commission. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionCountyTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission County Tabs item
commissionExpirationTabsarrayOptionalA list of
[Commission Expiration tabs][tabref].


A Commission Expiration tab displays the expiration date of a notary's commission. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[tabref]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionExpirationTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission Expiration Tabs item
commissionNumberTabsarrayOptionalA list of
[Commission Number tabs][tabref].


A Commission Number tab displays a notary's commission number. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[tabref]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionNumberTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission Number Tabs item
commissionStateTabsarrayOptionalA list of
[Commission State tabs][cc].


A Commission County tab displays the state in which a notary's commission was granted. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionStateTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission State Tabs item
companyTabsarrayOptionalA list of
[Company tabs][company].

A Company tab displays a field for the name of the recipient's company. This value can't be set.

[company]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#parameters_company
companyTabs[]ModelEach itemExpand Returns tabs on a template — response body — company Tabs item
dateSignedTabsarrayOptionalA list of
[Date Signed tabs][dateSigned].


A Date Signed tab displays the date that the recipient signed the document. This value can't be set.

[dateSigned]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
dateSignedTabs[]ModelEach itemExpand Returns tabs on a template — response body — date Signed Tabs item
dateTabsarrayOptionalA list of Date tabs.

A Date tab enables the recipient to enter a date either by typing or using a date-picker. If you provide a `value` for this tab, it becomes read-only. The tooltip shown to the signer will always show MM/DD/YYYY, but you can specify three different [regular expression](https://en.wikipedia.org/wiki/Regular_expression) (regex) validation patterns for the date by setting the `validationPattern` property. Your three choices are:
* DD/MM/YYYY: (((0[1-9])|([12][0-9])|(3[01])))
* MM/DD/YYYY: (((|0)[1-9]|1[0-2])/((|0)[1-9]|[1-2][0-9]|3[0-1])/[0-9]{4}$)
* YYYY/DD/MM: ([0-9]{4}/((|0)[1-9]|1[0-2])/((|0)[1-9]|[1-2][0-9]|3[0-1])
dateTabs[]ModelEach itemExpand Returns tabs on a template — response body — date Tabs item
declineTabsarrayOptionalA list of
[Decline tabs][decline].

A Decline tab enables the recipient to decline the envelope. If the recipient clicks the tab during the signing process, the envelope is voided. The value of this tab can't be set.


[decline]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
declineTabs[]ModelEach itemExpand Returns tabs on a template — response body — decline Tabs item
drawTabsarrayOptionalA list of Draw Tabs.

A Draw Tab allows the recipient to add a free-form drawing to the document.
drawTabs[]ModelEach itemExpand Returns tabs on a template — response body — draw Tabs item
emailAddressTabsarrayOptionalA list of
[Email Address tabs][emailAddress].

An Email Address tab displays the recipient's email as entered in the recipient information. This value can't be set.


[emailAddress]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
emailAddressTabs[]ModelEach itemExpand Returns tabs on a template — response body — email Address Tabs item
emailTabsarrayOptionalA list of
[Email tabs][email].

An Email tab enables the recipient to enter an email address.
This is a one-line field that checks that a valid email
address is entered. It uses the same parameters as a Text
tab, with the validation message and pattern set for email
information. This value can be set.

When getting information that includes
this tab type, the original value of the tab when the
associated envelope was sent is included in the response.

[email]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
emailTabs[]ModelEach itemExpand Returns tabs on a template — response body — email Tabs item
envelopeIdTabsarrayOptionalA list of
[Envelope ID tabs][envelopeId].

An Envelope ID tab displays the envelope ID. Recipients cannot enter or change the information in this tab. This value can't be set.


[envelopeId]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#response201_envelopeid
envelopeIdTabs[]ModelEach itemExpand Returns tabs on a template — response body — envelope Id Tabs item
firstNameTabsarrayOptionalA list of
[First Name tabs][firstName].

A First Name tab displays the recipient's first name. The system automatically populates this field by splitting the name in the recipient information on spaces. This value can't be set.


[firstName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#parameters_firstname
firstNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — first Name Tabs item
formulaTabsarrayOptionalA list of [Formula tabs][formulaTab].

The value of a Formula tab is calculated from the values of other number or date tabs in the document. When the recipient completes the underlying fields, the Formula tab calculates and displays the result. This value can be set.

The `formula` property of the tab contains the references to the underlying tabs. To learn more about formulas, see [Calculated Fields][calculatedfields].

If a Formula tab contains a `paymentDetails` property, the tab is considered a payment item. To learn more about payments, see [Requesting Payments Along with Signatures][paymentguide].

[calculatedfields]: https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=crs1578456361259.html
[paymentguide]: https://support.docusign.com/s/document-item?bundleId=juu1573854950452&topicId=fyw1573854935374.html
[formulaTab]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
formulaTabs[]ModelEach itemExpand Returns tabs on a template — response body — formula Tabs item
fullNameTabsarrayOptionalA list of
[Full Name tabs][fullName].

A Full Name tab displays the recipient's full name. This value can't be set.


[fullName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
fullNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — full Name Tabs item
initialHereTabsarrayOptionalA list of
[Initial Here tabs][initialHere].

This type of tab enables the recipient to initial the document. May be optional. This value can't be set.

[initialHere]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
initialHereTabs[]ModelEach itemExpand Returns tabs on a template — response body — initial Here Tabs item
lastNameTabsarrayOptionalA list of
[Last Name tabs][lastName].

A Last Name tab displays the recipient's last name. The system automatically populates this field by splitting the name in the recipient information on spaces. This value can't be set.


[lastName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
lastNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — last Name Tabs item
listTabsarrayOptionalAn array of List tabs.

A List tab enables the recipient to choose from a list of options. You specify the options in the `listItems` property. This value can't be set.

Find descriptions of all tab types in
the [EnvelopeRecipientTabs Resource][ert].

[ert]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
listTabs[]ModelEach itemExpand Returns tabs on a template — response body — list Tabs item
notarizeTabsarrayOptionalA list of [Notarize tabs][notarize].

A Notarize tab alerts notary recipients that they must take action on the page. This value can be set.

**Note:** Only one notarize tab can appear on a page.

[notarize]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
notarizeTabs[]ModelEach itemExpand Returns tabs on a template — response body — notarize Tabs item
notarySealTabsarrayOptionalA list of Notary Seal tabs.

A Notary Seal tab enables the recipient to notarize a document. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary].

[notary]: /docs/notary-api/
notarySealTabs[]ModelEach itemExpand Returns tabs on a template — response body — notary Seal Tabs item
noteTabsarrayOptionalA list of
[Note tabs][note].

A Note tab displays additional information to the recipient in the form of a note. This value can be set.

[note]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
noteTabs[]ModelEach itemExpand Returns tabs on a template — response body — note Tabs item
numberTabsarrayOptionalA list of Number tabs.

Number tabs validate that the entered value is a number.
They do not support advanced validation or display options.

To learn more about the different forms of number tabs,
see [Number fields](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/) in the Concepts guide.
For specific information about number tabs
see [Features of numberTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/#features-of-numbertabs).

[number]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
numberTabs[]ModelEach itemExpand Returns tabs on a template — response body — number Tabs item
numericalTabsarrayOptionalA list of numerical tabs.

Numerical tabs provide robust display and validation features, including formatting for different regions and currencies, and minimum and maximum value validation.

To learn more about the different forms of number tabs,
see [Number fields](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/) in the Concepts guide.
For specific information about numerical tabs
see [Features of numericalTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/#features-of-numericaltabs).
numericalTabs[]ModelEach itemExpand Returns tabs on a template — response body — numerical Tabs item
phoneNumberTabsarrayOptionalA list of
[Phone Number tabs][cc].


A Phone Number tab enables a recipient to enter a phone number.

**Note:** This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary].

[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
phoneNumberTabs[]ModelEach itemExpand Returns tabs on a template — response body — phone Number Tabs item
polyLineOverlayTabsarrayOptionalThis type of tab enables the recipient to strike through document text. This value can't be set.
polyLineOverlayTabs[]ModelEach itemExpand Returns tabs on a template — response body — poly Line Overlay Tabs item
prefillTabsModelOptionalExpand Returns tabs on a template — response body — prefill Tabs
Prefill tabs are tabs
that the sender can fill in
before the envelope is sent.
They are sometimes called
sender tags or pre-fill fields.


[Pre-Fill Your Own Document Fields][app]
describes how prefill tabs
work in the web application.


[Customize your envelopes with pre-fill fields][catblog]
shows how to use prefill tabs
in your application using the eSignature
SDKs.

[app]: https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=nwo1611173513994.html
[catblog]: https://www.docusign.com/blog/developers/common-api-tasks-customize-your-envelopes-pre-fill-fields
radioGroupTabsarrayOptionalA list of [Radio Group tabs][radioGroup].

A Radio Group tab places a group of radio buttons on a document. The `radios` property is used to add and place the radio
buttons associated with the group. Only one radio button can be selected in a group. This value can be set.


[radioGroup]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
radioGroupTabs[]ModelEach itemExpand Returns tabs on a template — response body — radio Group Tabs item
signHereTabsarrayOptionalA list of
[Sign Here tabs][signHere].

This type of tab enables the recipient to sign a document. May be optional. This value can't be set.

[signHere]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
signHereTabs[]ModelEach itemExpand Returns tabs on a template — response body — sign Here Tabs item
signerAttachmentTabsarrayOptionalA list of
[Signer Attachment tabs][signerAttachment].

This type of tab enables the recipient to attach supporting documents to an envelope. This value can't be set.


[signerAttachment]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
signerAttachmentTabs[]ModelEach itemExpand Returns tabs on a template — response body — signer Attachment Tabs item
smartSectionTabsarrayOptionalA list of [Smart Section](https://www.docusign.com/blog/dsdev-deep-dive-responsive-smart-sections) tabs.

Smart Section tabs enhance responsive signing on mobile devices by enabling collapsible sections, page breaks, custom formatting options, and other advanced functionality.

**Note:** Smart Sections are a premium feature. Responsive signing must also be enabled for your account.
smartSectionTabs[]ModelEach itemExpand Deletes tabs from a template — request body — body smart Section Tabs item
ssnTabsarrayOptionalA list of
[SSN tabs][ssn].

An SSN tab contains a one-line field that enables the recipient to enter a Social Security Number (SSN) with or without
dashes. It uses the same parameters as a Text tab, with the validation message and pattern set for SSN information. This value can be set.


[ssn]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
ssnTabs[]ModelEach itemExpand Returns tabs on a template — response body — ssn Tabs item
tabGroupsarrayOptionalAn array of `tabGroup` items.

To associate a tab with a tab group, add the tab group's `groupLabel` to the tab's `tabGroupLabels` array.
tabGroups[]ModelEach itemExpand Returns tabs on a template — response body — tab Groups item
textTabsarrayOptionalA list of
Text tabs.

A text tab enables the recipient to enter free text. This value can be set.

Find descriptions of all tab types in
the [EnvelopeRecipientTabs Resource][ert].

[ert]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
textTabs[]ModelEach itemExpand Returns tabs on a template — response body — text Tabs item
titleTabsarrayOptionalA list of
[Title tabs][title].

A Title tab displays the recipient's title. This value can't be set.


[title]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
titleTabs[]ModelEach itemExpand Returns tabs on a template — response body — title Tabs item
viewTabsarrayOptionalA list of
[View tabs][view].

A View tab is used with an Approve tab to handle supplemental documents. This value can be set.

[view]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
viewTabs[]ModelEach itemExpand Returns tabs on a template — response body — view Tabs item
zipTabsarrayOptionalA list of
[Zip tabs][zip].

A Zip tab enables the recipient to enter a ZIP code. The ZIP code can be five digits or nine digits ( in ZIP+4 format), and can be entered with or without dashes. It uses the same parameters as a Text tab, with the validation message and pattern set for ZIP code information. This value can be set.


[zip]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
zipTabs[]ModelEach itemExpand Returns tabs on a template — response body — zip Tabs item

Referenced models: Returns tabs on a template — response body — approve Tabs item, Returns tabs on a template — response body — checkbox Tabs item, Returns tabs on a template — response body — comment Thread Tabs item, Returns tabs on a template — response body — commission County Tabs item, Returns tabs on a template — response body — commission Expiration Tabs item, Returns tabs on a template — response body — commission Number Tabs item, Returns tabs on a template — response body — commission State Tabs item, Returns tabs on a template — response body — company Tabs item, Returns tabs on a template — response body — date Tabs item, Returns tabs on a template — response body — date Signed Tabs item, Returns tabs on a template — response body — decline Tabs item, Returns tabs on a template — response body — draw Tabs item, Returns tabs on a template — response body — email Tabs item, Returns tabs on a template — response body — email Address Tabs item, Returns tabs on a template — response body — envelope Id Tabs item, Returns tabs on a template — response body — first Name Tabs item, Returns tabs on a template — response body — formula Tabs item, Returns tabs on a template — response body — full Name Tabs item, Returns tabs on a template — response body — initial Here Tabs item, Returns tabs on a template — response body — last Name Tabs item, Returns tabs on a template — response body — list Tabs item, Returns tabs on a template — response body — notarize Tabs item, Returns tabs on a template — response body — notary Seal Tabs item, Returns tabs on a template — response body — note Tabs item, Returns tabs on a template — response body — number Tabs item, Returns tabs on a template — response body — numerical Tabs item, Returns tabs on a template — response body — phone Number Tabs item, Returns tabs on a template — response body — poly Line Overlay Tabs item, Returns tabs on a template — response body — prefill Tabs, Returns tabs on a template — response body — radio Group Tabs item, Returns tabs on a template — response body — sign Here Tabs item, Returns tabs on a template — response body — signer Attachment Tabs item, Returns tabs on a template — response body — ssn Tabs item, Returns tabs on a template — response body — tab Groups item, Returns tabs on a template — response body — text Tabs item, Returns tabs on a template — response body — title Tabs item, Returns tabs on a template — response body — view Tabs item, Returns tabs on a template — response body — zip Tabs item, Deletes tabs from a template — request body — body smart Section Tabs item

Adds tabs for a recipient — esignature esignature Recipients Post Recipient Tabs — response body

FieldTypePresenceDescription and constraints
$objectRootAll of the tabs associated with a recipient. Each property is a list of a type of tab.
approveTabsarrayOptionalA list of
[Approve tabs][approve].

An Approve tab enables
the recipient to approve documents without
placing a signature or initials on the document. If the
recipient clicks the tab during the signing process, the
recipient is considered to have signed the document. No
information is shown on the document of the approval, but it
is recorded as a signature in the envelope history.
The value of an approve tab can't be set.

[approve]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
approveTabs[]ModelEach itemExpand Returns tabs on a template — response body — approve Tabs item
checkboxTabsarrayOptionalA list of
[Checkbox tabs][checkbox].


A Checkbox tab enables the recipient to select a yes/no (on/off) option. This value can be set.


[checkbox]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
checkboxTabs[]ModelEach itemExpand Returns tabs on a template — response body — checkbox Tabs item
commentThreadTabsarrayOptionalAn array of tabs that represents a collection of comments in a comment thread. For example, if a recipient has questions about the content of a document, they can add a comment to the document and control who else can see the comment. This value can't be set.
commentThreadTabs[]ModelEach itemExpand Returns tabs on a template — response body — comment Thread Tabs item
commissionCountyTabsarrayOptionalA list of
[Commission County tabs][cc].


A Commission County tab displays the county of a notary's commission. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionCountyTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission County Tabs item
commissionExpirationTabsarrayOptionalA list of
[Commission Expiration tabs][tabref].


A Commission Expiration tab displays the expiration date of a notary's commission. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[tabref]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionExpirationTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission Expiration Tabs item
commissionNumberTabsarrayOptionalA list of
[Commission Number tabs][tabref].


A Commission Number tab displays a notary's commission number. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[tabref]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionNumberTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission Number Tabs item
commissionStateTabsarrayOptionalA list of
[Commission State tabs][cc].


A Commission County tab displays the state in which a notary's commission was granted. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary]. The tab's value can be edited by the recipient.


[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
commissionStateTabs[]ModelEach itemExpand Returns tabs on a template — response body — commission State Tabs item
companyTabsarrayOptionalA list of
[Company tabs][company].

A Company tab displays a field for the name of the recipient's company. This value can't be set.

[company]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#parameters_company
companyTabs[]ModelEach itemExpand Returns tabs on a template — response body — company Tabs item
dateSignedTabsarrayOptionalA list of
[Date Signed tabs][dateSigned].


A Date Signed tab displays the date that the recipient signed the document. This value can't be set.

[dateSigned]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
dateSignedTabs[]ModelEach itemExpand Returns tabs on a template — response body — date Signed Tabs item
dateTabsarrayOptionalA list of Date tabs.

A Date tab enables the recipient to enter a date either by typing or using a date-picker. If you provide a `value` for this tab, it becomes read-only. The tooltip shown to the signer will always show MM/DD/YYYY, but you can specify three different [regular expression](https://en.wikipedia.org/wiki/Regular_expression) (regex) validation patterns for the date by setting the `validationPattern` property. Your three choices are:
* DD/MM/YYYY: (((0[1-9])|([12][0-9])|(3[01])))
* MM/DD/YYYY: (((|0)[1-9]|1[0-2])/((|0)[1-9]|[1-2][0-9]|3[0-1])/[0-9]{4}$)
* YYYY/DD/MM: ([0-9]{4}/((|0)[1-9]|1[0-2])/((|0)[1-9]|[1-2][0-9]|3[0-1])
dateTabs[]ModelEach itemExpand Returns tabs on a template — response body — date Tabs item
declineTabsarrayOptionalA list of
[Decline tabs][decline].

A Decline tab enables the recipient to decline the envelope. If the recipient clicks the tab during the signing process, the envelope is voided. The value of this tab can't be set.


[decline]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
declineTabs[]ModelEach itemExpand Returns tabs on a template — response body — decline Tabs item
drawTabsarrayOptionalA list of Draw Tabs.

A Draw Tab allows the recipient to add a free-form drawing to the document.
drawTabs[]ModelEach itemExpand Returns tabs on a template — response body — draw Tabs item
emailAddressTabsarrayOptionalA list of
[Email Address tabs][emailAddress].

An Email Address tab displays the recipient's email as entered in the recipient information. This value can't be set.


[emailAddress]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
emailAddressTabs[]ModelEach itemExpand Returns tabs on a template — response body — email Address Tabs item
emailTabsarrayOptionalA list of
[Email tabs][email].

An Email tab enables the recipient to enter an email address.
This is a one-line field that checks that a valid email
address is entered. It uses the same parameters as a Text
tab, with the validation message and pattern set for email
information. This value can be set.

When getting information that includes
this tab type, the original value of the tab when the
associated envelope was sent is included in the response.

[email]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
emailTabs[]ModelEach itemExpand Returns tabs on a template — response body — email Tabs item
envelopeIdTabsarrayOptionalA list of
[Envelope ID tabs][envelopeId].

An Envelope ID tab displays the envelope ID. Recipients cannot enter or change the information in this tab. This value can't be set.


[envelopeId]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#response201_envelopeid
envelopeIdTabs[]ModelEach itemExpand Returns tabs on a template — response body — envelope Id Tabs item
firstNameTabsarrayOptionalA list of
[First Name tabs][firstName].

A First Name tab displays the recipient's first name. The system automatically populates this field by splitting the name in the recipient information on spaces. This value can't be set.


[firstName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/create/#parameters_firstname
firstNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — first Name Tabs item
formulaTabsarrayOptionalA list of [Formula tabs][formulaTab].

The value of a Formula tab is calculated from the values of other number or date tabs in the document. When the recipient completes the underlying fields, the Formula tab calculates and displays the result. This value can be set.

The `formula` property of the tab contains the references to the underlying tabs. To learn more about formulas, see [Calculated Fields][calculatedfields].

If a Formula tab contains a `paymentDetails` property, the tab is considered a payment item. To learn more about payments, see [Requesting Payments Along with Signatures][paymentguide].

[calculatedfields]: https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=crs1578456361259.html
[paymentguide]: https://support.docusign.com/s/document-item?bundleId=juu1573854950452&topicId=fyw1573854935374.html
[formulaTab]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
formulaTabs[]ModelEach itemExpand Returns tabs on a template — response body — formula Tabs item
fullNameTabsarrayOptionalA list of
[Full Name tabs][fullName].

A Full Name tab displays the recipient's full name. This value can't be set.


[fullName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
fullNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — full Name Tabs item
initialHereTabsarrayOptionalA list of
[Initial Here tabs][initialHere].

This type of tab enables the recipient to initial the document. May be optional. This value can't be set.

[initialHere]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
initialHereTabs[]ModelEach itemExpand Returns tabs on a template — response body — initial Here Tabs item
lastNameTabsarrayOptionalA list of
[Last Name tabs][lastName].

A Last Name tab displays the recipient's last name. The system automatically populates this field by splitting the name in the recipient information on spaces. This value can't be set.


[lastName]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
lastNameTabs[]ModelEach itemExpand Returns tabs on a template — response body — last Name Tabs item
listTabsarrayOptionalAn array of List tabs.

A List tab enables the recipient to choose from a list of options. You specify the options in the `listItems` property. This value can't be set.

Find descriptions of all tab types in
the [EnvelopeRecipientTabs Resource][ert].

[ert]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
listTabs[]ModelEach itemExpand Returns tabs on a template — response body — list Tabs item
notarizeTabsarrayOptionalA list of [Notarize tabs][notarize].

A Notarize tab alerts notary recipients that they must take action on the page. This value can be set.

**Note:** Only one notarize tab can appear on a page.

[notarize]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
notarizeTabs[]ModelEach itemExpand Returns tabs on a template — response body — notarize Tabs item
notarySealTabsarrayOptionalA list of Notary Seal tabs.

A Notary Seal tab enables the recipient to notarize a document. This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary].

[notary]: /docs/notary-api/
notarySealTabs[]ModelEach itemExpand Returns tabs on a template — response body — notary Seal Tabs item
noteTabsarrayOptionalA list of
[Note tabs][note].

A Note tab displays additional information to the recipient in the form of a note. This value can be set.

[note]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
noteTabs[]ModelEach itemExpand Returns tabs on a template — response body — note Tabs item
numberTabsarrayOptionalA list of Number tabs.

Number tabs validate that the entered value is a number.
They do not support advanced validation or display options.

To learn more about the different forms of number tabs,
see [Number fields](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/) in the Concepts guide.
For specific information about number tabs
see [Features of numberTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/#features-of-numbertabs).

[number]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
numberTabs[]ModelEach itemExpand Returns tabs on a template — response body — number Tabs item
numericalTabsarrayOptionalA list of numerical tabs.

Numerical tabs provide robust display and validation features, including formatting for different regions and currencies, and minimum and maximum value validation.

To learn more about the different forms of number tabs,
see [Number fields](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/) in the Concepts guide.
For specific information about numerical tabs
see [Features of numericalTabs](/docs/esign-rest-api/esign101/concepts/tabs/number-fields/#features-of-numericaltabs).
numericalTabs[]ModelEach itemExpand Returns tabs on a template — response body — numerical Tabs item
phoneNumberTabsarrayOptionalA list of
[Phone Number tabs][cc].


A Phone Number tab enables a recipient to enter a phone number.

**Note:** This tab can only be assigned to a remote notary recipient using [Docusign Notary][notary].

[cc]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
[notary]: /docs/notary-api/
phoneNumberTabs[]ModelEach itemExpand Returns tabs on a template — response body — phone Number Tabs item
polyLineOverlayTabsarrayOptionalThis type of tab enables the recipient to strike through document text. This value can't be set.
polyLineOverlayTabs[]ModelEach itemExpand Returns tabs on a template — response body — poly Line Overlay Tabs item
prefillTabsModelOptionalExpand Returns tabs on a template — response body — prefill Tabs
Prefill tabs are tabs
that the sender can fill in
before the envelope is sent.
They are sometimes called
sender tags or pre-fill fields.


[Pre-Fill Your Own Document Fields][app]
describes how prefill tabs
work in the web application.


[Customize your envelopes with pre-fill fields][catblog]
shows how to use prefill tabs
in your application using the eSignature
SDKs.

[app]: https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=nwo1611173513994.html
[catblog]: https://www.docusign.com/blog/developers/common-api-tasks-customize-your-envelopes-pre-fill-fields
radioGroupTabsarrayOptionalA list of [Radio Group tabs][radioGroup].

A Radio Group tab places a group of radio buttons on a document. The `radios` property is used to add and place the radio
buttons associated with the group. Only one radio button can be selected in a group. This value can be set.


[radioGroup]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
radioGroupTabs[]ModelEach itemExpand Returns tabs on a template — response body — radio Group Tabs item
signHereTabsarrayOptionalA list of
[Sign Here tabs][signHere].

This type of tab enables the recipient to sign a document. May be optional. This value can't be set.

[signHere]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
signHereTabs[]ModelEach itemExpand Returns tabs on a template — response body — sign Here Tabs item
signerAttachmentTabsarrayOptionalA list of
[Signer Attachment tabs][signerAttachment].

This type of tab enables the recipient to attach supporting documents to an envelope. This value can't be set.


[signerAttachment]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
signerAttachmentTabs[]ModelEach itemExpand Returns tabs on a template — response body — signer Attachment Tabs item
smartSectionTabsarrayOptionalA list of [Smart Section](https://www.docusign.com/blog/dsdev-deep-dive-responsive-smart-sections) tabs.

Smart Section tabs enhance responsive signing on mobile devices by enabling collapsible sections, page breaks, custom formatting options, and other advanced functionality.

**Note:** Smart Sections are a premium feature. Responsive signing must also be enabled for your account.
smartSectionTabs[]ModelEach itemExpand Returns tabs on a template — response body — smart Section Tabs item
ssnTabsarrayOptionalA list of
[SSN tabs][ssn].

An SSN tab contains a one-line field that enables the recipient to enter a Social Security Number (SSN) with or without
dashes. It uses the same parameters as a Text tab, with the validation message and pattern set for SSN information. This value can be set.


[ssn]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
ssnTabs[]ModelEach itemExpand Returns tabs on a template — response body — ssn Tabs item
tabGroupsarrayOptionalAn array of `tabGroup` items.

To associate a tab with a tab group, add the tab group's `groupLabel` to the tab's `tabGroupLabels` array.
tabGroups[]ModelEach itemExpand Returns tabs on a template — response body — tab Groups item
textTabsarrayOptionalA list of
Text tabs.

A text tab enables the recipient to enter free text. This value can be set.

Find descriptions of all tab types in
the [EnvelopeRecipientTabs Resource][ert].

[ert]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
textTabs[]ModelEach itemExpand Returns tabs on a template — response body — text Tabs item
titleTabsarrayOptionalA list of
[Title tabs][title].

A Title tab displays the recipient's title. This value can't be set.


[title]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
titleTabs[]ModelEach itemExpand Returns tabs on a template — response body — title Tabs item
viewTabsarrayOptionalA list of
[View tabs][view].

A View tab is used with an Approve tab to handle supplemental documents. This value can be set.

[view]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
viewTabs[]ModelEach itemExpand Returns tabs on a template — response body — view Tabs item
zipTabsarrayOptionalA list of
[Zip tabs][zip].

A Zip tab enables the recipient to enter a ZIP code. The ZIP code can be five digits or nine digits ( in ZIP+4 format), and can be entered with or without dashes. It uses the same parameters as a Text tab, with the validation message and pattern set for ZIP code information. This value can be set.


[zip]: /docs/esign-rest-api/reference/envelopes/enveloperecipienttabs/
zipTabs[]ModelEach itemExpand Returns tabs on a template — response body — zip Tabs item

Referenced models: Returns tabs on a template — response body — approve Tabs item, Returns tabs on a template — response body — checkbox Tabs item, Returns tabs on a template — response body — comment Thread Tabs item, Returns tabs on a template — response body — commission County Tabs item, Returns tabs on a template — response body — commission Expiration Tabs item, Returns tabs on a template — response body — commission Number Tabs item, Returns tabs on a template — response body — commission State Tabs item, Returns tabs on a template — response body — company Tabs item, Returns tabs on a template — response body — date Tabs item, Returns tabs on a template — response body — date Signed Tabs item, Returns tabs on a template — response body — decline Tabs item, Returns tabs on a template — response body — draw Tabs item, Returns tabs on a template — response body — email Tabs item, Returns tabs on a template — response body — email Address Tabs item, Returns tabs on a template — response body — envelope Id Tabs item, Returns tabs on a template — response body — first Name Tabs item, Returns tabs on a template — response body — formula Tabs item, Returns tabs on a template — response body — full Name Tabs item, Returns tabs on a template — response body — initial Here Tabs item, Returns tabs on a template — response body — last Name Tabs item, Returns tabs on a template — response body — list Tabs item, Returns tabs on a template — response body — notarize Tabs item, Returns tabs on a template — response body — notary Seal Tabs item, Returns tabs on a template — response body — note Tabs item, Returns tabs on a template — response body — number Tabs item, Returns tabs on a template — response body — numerical Tabs item, Returns tabs on a template — response body — phone Number Tabs item, Returns tabs on a template — response body — poly Line Overlay Tabs item, Returns tabs on a template — response body — prefill Tabs, Returns tabs on a template — response body — radio Group Tabs item, Returns tabs on a template — response body — sign Here Tabs item, Returns tabs on a template — response body — signer Attachment Tabs item, Returns tabs on a template — response body — smart Section Tabs item, Returns tabs on a template — response body — ssn Tabs item, Returns tabs on a template — response body — tab Groups item, Returns tabs on a template — response body — text Tabs item, Returns tabs on a template — response body — title Tabs item, Returns tabs on a template — response body — view Tabs item, Returns tabs on a template — response body — zip Tabs item

Adds templates to an envelope — response body

FieldTypePresenceDescription and constraints
$objectRoot
documentTemplatesarrayOptional
documentTemplates[]ModelEach itemExpand Adds templates to an envelope — response body — document Templates item

Referenced models: Adds templates to an envelope — response body — document Templates item

Adds templates to an envelope — response body — document Templates item

FieldTypePresenceDescription and constraints
$objectRoot
documentEndPagestringOptional
documentIdstringOptionalSpecifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
documentStartPagestringOptional
errorDetailsModelOptionalExpand Locks a template — response body — error Details
This object describes errors that occur. It is only valid for responses and ignored in requests.
templateIdstringOptionalThe unique identifier of the template. If this is not provided, Docusign generates an error and the call fails.

Referenced models: Locks a template — response body — error Details

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.