Skip to navigation
Docusign eSignature REST APICustomTabsCustomTabs

Create custom tab

View as Markdown

Creates a tab with pre-defined properties, such as a text tab with a certain font type and validation pattern. Users can access the custom tabs when sending documents through the DocuSign web application.

Custom tabs can be created for approve, checkbox, company, date, date signed, decline, email, email address, envelope ID, first name, formula, full name, initial here, last name, list, note, number, radio, sign here, signer attachment, SSN, text, title, and zip tabs.

Authentication

AuthorizationBearer

OAuth 2.0 access token (JWT or auth-code grant). Sent as Authorization: Bearer <token> on every request except GET /v2.1 and GET /service_information, which are public discovery endpoints.

Path parameters

accountIdstringRequired

The external account number (int) or account ID Guid.

Request

This endpoint expects an object: tabMetadata

anchorstringOptional

An optional string that is used to auto-match tabs to strings located in the documents of an envelope.

anchorCaseSensitivestringOptional

This property controls how anchor tabs are placed. When true, the text string in a document must match the case of the anchorString property for an anchor tab to be created. The default value is false.

For example, when set to true, if the anchor string is DocuSign, then DocuSign will match; but Docusign, docusign, DoCuSiGn, etc. will not match. When false, DocuSign, Docusign, docusign, DoCuSiGn, etc. will all match.

This functionality uses the following rules:

  • Unless punctuation is specified in the anchorString, this functionality ignores punctuation and the following characters:

$~><|^+=

For example, the anchorString water will match on the string Fetch a pail of water.

  • Strings embedded in other strings are ignored during the matching process.

  • In words that have dashes, the parts separated by dashes are treated as distinct words.

Example: If the anchor string is forget, then an anchor tab is placed on the forget in forget-me-not, even when anchorMatchWholeWord is set to true.

  • Letters with accent marks are treated as distinct characters from their unaccented counterparts.

  • For single-character anchor strings, if the two characters appear next to each other in the document, a single anchor tab is placed for both of them.

Example: If the anchor string is i, then only one anchor tab is placed in skiing.

  • Unlike punctuation, numbers are not ignored when finding anchor words.

Example: If the anchor string is cat, then -cat- is matched, but 1cat2 is not when anchorMatchWholeWord is set to true (its default value).

Note: You can only specify the value of this property in POST requests.

anchorHorizontalAlignmentstringOptional

This property controls how anchor tabs are aligned in relation to the anchor text. Possible values are :

  • left: Aligns the left side of the tab with the beginning of the first character of the matching anchor word. This is the default value.
  • right: Aligns the tab’s left side with the last character of the matching anchor word.

Note: You can only specify the value of this property in POST requests.

anchorIgnoreIfNotPresentstringOptional

When true, this tab is ignored if the anchorString is not found in the document.

anchorMatchWholeWordstringOptional

When true, the text string in a document must match the value of the anchorString property in its entirety for an anchor tab to be created. The default value is false.

For example, when set to true, if the input is man, then man will match; but manpower, fireman, and penmanship will not. When false, if the input is man then man, manpower, fireman, and penmanship will all match.

This functionality uses the following rules:

  • Unless punctuation is specified in the anchorString, this functionality ignores punctuation and the following characters:

$~><|^+=

For example, the anchorString water will match on the string Fetch a pail of water.

  • Strings embedded in other strings are ignored during the matching process.

  • In words that have dashes, the parts separated by dashes are treated as distinct words.

Example: If the anchor string is forget, then an anchor tab is placed on the forget in forget-me-not, even when anchorMatchWholeWord is set to true.

  • Letters with accent marks are treated as distinct characters from their unaccented counterparts.

  • For single-character anchor strings, if the two characters appear next to each other in the document, a single anchor tab is placed for both of them.

Example: If the anchor string is i, then only one anchor tab is placed in skiing.

  • Unlike punctuation, numbers are not ignored when finding anchor words.

Example: If the anchor string is cat, then -cat- is matched, but 1cat2 is not when anchorMatchWholeWord is set to true (its default value).

Note: You can only specify the value of this property in POST requests.

anchorUnitsstringOptional

Specifies units of the anchorXOffset and anchorYOffset. Valid units are:

  • pixels (default)
  • inches
  • mms
  • cms
anchorXOffsetstringOptional
Specifies the X axis location of the tab, in anchorUnits, relative to the anchorString.
anchorYOffsetstringOptional
Specifies the Y axis location of the tab, in anchorUnits, relative to the anchorString.
boldstringOptional

When true, the information in the tab is bold.

collaborativestringOptional

When true, the tab can be edited by any recipient during signing.

concealValueOnDocumentstringOptional

When true, the field appears normally while the recipient is adding or modifying the information in the field, but the data is not visible (the characters are hidden by asterisks) to any other signer or the sender.

When an envelope is completed, the information is only available to the sender through the Form Data link in the Docusign console. The information on the downloaded document remains masked by asterisks.

This setting applies only to text boxes and does not affect list boxes, radio buttons, or check boxes.

createdByDisplayNamestringOptional
The user name of the DocuSign user who created this object.
createdByUserIdstringOptional
The userId of the DocuSign user who created this object.
customTabIdstringOptional
The DocuSign generated custom tab ID for the custom tab to be applied. This can only be used when adding new tabs for a recipient. When used, the new tab inherits all the custom tab properties.
disableAutoSizestringOptional

When true, disables the auto-sizing of single-line text boxes in the signing screen when the signer enters data. If auto-sizing is disabled, users will only be able enter as much data as the text box can hold. By default this is false. This property only affects single-line text boxes.

editablestringOptional

When true, the custom tab is editable. Otherwise the custom tab cannot be modified.

fontstringOptional

The font to be used for the tab value. Supported fonts include:

  • Default
  • Arial
  • ArialNarrow
  • Calibri
  • CourierNew
  • Garamond
  • Georgia
  • Helvetica
  • LucidaConsole
  • MSGothic
  • MSMincho
  • OcrA (OCR-A)
  • Tahoma
  • TimesNewRoman
  • Trebuchet
  • Verdana
fontColorstringOptional

The font color to use for the information in the tab. Possible values are:

  • Black
  • BrightBlue
  • BrightRed
  • DarkGreen
  • DarkRed
  • Gold
  • Green
  • NavyBlue
  • Purple
  • White
fontSizestringOptional

The font size used for the information in the tab. Possible values are:

  • Size7
  • Size8
  • Size9
  • Size10
  • Size11
  • Size12
  • Size14
  • Size16
  • Size18
  • Size20
  • Size22
  • Size24
  • Size26
  • Size28
  • Size36
  • Size48
  • Size72
heightstringOptional
The height of the tab in pixels. Must be an integer.
includedInEmailstringOptional

When true, the tab is included in emails related to the envelope on which it exists. This applies to only specific tabs.

initialValuestringOptional
The original value of the tab.
italicstringOptional

When true, the information in the tab is italic.

itemslist of stringsOptional
If the tab is a list, this represents the values that are possible for the tab.
lastModifiedstringOptional
The UTC DateTime this object was last modified. This is in ISO8601 format.
lastModifiedByDisplayNamestringOptional
The User Name of the DocuSign user who last modified this object.
lastModifiedByUserIdstringOptional
The userId of the DocuSign user who last modified this object.
localePolicyobjectOptional
Allows you to customize locale settings.
lockedstringOptional

When true, the signer cannot change the data of the custom tab.

maximumLengthstringOptional
The maximum number of entry characters supported by the custom tab.
maxNumericalValuestringOptional
mergeFieldobjectOptional
Contains information for transferring values between Salesforce data fields and Docusign tabs.
minNumericalValuestringOptional
namestringOptional
numericalValuestringOptional
paymentItemCodestringOptional

If the custom tab is for a payment request, this is the external code for the item associated with the charge. For example, this might be your product id.

Example: SHAK1

Maximum Length: 100 characters.

paymentItemDescriptionstringOptional

If the custom tab is for a payment request, this is the description of the item associated with the charge.

Example: The Danish play by Shakespeare

Maximum Length: 100 characters.

paymentItemNamestringOptional

If the custom tab is for a payment request, this is the name of the item associated with the charge.

Maximum Length: 100 characters.

Example: Hamlet

requireAllstringOptional

When true and shared is true, information must be entered in this field to complete the envelope.

requiredstringOptional

When true, the signer is required to fill out this tab.

requireInitialOnSharedChangestringOptional

Optional element for field markup. When true, the signer is required to initial when they modify a shared field.

scaleValuestringOptional

Sets the size of the tab. This field accepts values from 0.5 to 1.0, where 1.0 represents full size and 0.5 is 50% of full size.

selectedstringOptional

When true, the radio button is selected.

sharedstringOptional

When true, the tab is shared with all users on the account.

signatureProviderIdstringOptional
Reserved for Docusign.
stampTypestringOptional

The type of stamp. Valid values are:

  • signature: A signature image. This is the default value.
  • stamp: A stamp image.
  • null
stampTypeMetadataobjectOptional
Metadata about a property.
tabLabelstringOptional

The 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.

typestringOptional

The type of this tab. Values are:

  • Approve
  • CheckBox
  • Company
  • Date
  • DateSigned
  • Decline
  • Email
  • EmailAddress
  • EnvelopeId
  • FirstName
  • Formula
  • FullName
  • InitialHere
  • InitialHereOptional
  • LastName
  • List
  • Note
  • Number
  • Radio
  • SignerAttachment
  • SignHere
  • SignHereOptional
  • Ssn
  • Text
  • Title
  • Zip5
  • Zip5Dash4
underlinestringOptional

When true, the information in the tab is underlined.

validationMessagestringOptional

The message displayed if the custom tab fails input validation (either custom or embedded).

validationPatternstringOptional
A regular expression used to validate input for the tab.
validationTypestringOptional

Specifies how numerical data is validated. Valid values:

  • number
  • currency
widthstringOptional
The width of the tab in pixels. Must be an integer.

Response

Successful response.
anchorstringOptional

An optional string that is used to auto-match tabs to strings located in the documents of an envelope.

anchorCaseSensitivestringOptional

This property controls how anchor tabs are placed. When true, the text string in a document must match the case of the anchorString property for an anchor tab to be created. The default value is false.

For example, when set to true, if the anchor string is DocuSign, then DocuSign will match; but Docusign, docusign, DoCuSiGn, etc. will not match. When false, DocuSign, Docusign, docusign, DoCuSiGn, etc. will all match.

This functionality uses the following rules:

  • Unless punctuation is specified in the anchorString, this functionality ignores punctuation and the following characters:

$~><|^+=

For example, the anchorString water will match on the string Fetch a pail of water.

  • Strings embedded in other strings are ignored during the matching process.

  • In words that have dashes, the parts separated by dashes are treated as distinct words.

Example: If the anchor string is forget, then an anchor tab is placed on the forget in forget-me-not, even when anchorMatchWholeWord is set to true.

  • Letters with accent marks are treated as distinct characters from their unaccented counterparts.

  • For single-character anchor strings, if the two characters appear next to each other in the document, a single anchor tab is placed for both of them.

Example: If the anchor string is i, then only one anchor tab is placed in skiing.

  • Unlike punctuation, numbers are not ignored when finding anchor words.

Example: If the anchor string is cat, then -cat- is matched, but 1cat2 is not when anchorMatchWholeWord is set to true (its default value).

Note: You can only specify the value of this property in POST requests.

anchorHorizontalAlignmentstringOptional

This property controls how anchor tabs are aligned in relation to the anchor text. Possible values are :

  • left: Aligns the left side of the tab with the beginning of the first character of the matching anchor word. This is the default value.
  • right: Aligns the tab’s left side with the last character of the matching anchor word.

Note: You can only specify the value of this property in POST requests.

anchorIgnoreIfNotPresentstringOptional

When true, this tab is ignored if the anchorString is not found in the document.

anchorMatchWholeWordstringOptional

When true, the text string in a document must match the value of the anchorString property in its entirety for an anchor tab to be created. The default value is false.

For example, when set to true, if the input is man, then man will match; but manpower, fireman, and penmanship will not. When false, if the input is man then man, manpower, fireman, and penmanship will all match.

This functionality uses the following rules:

  • Unless punctuation is specified in the anchorString, this functionality ignores punctuation and the following characters:

$~><|^+=

For example, the anchorString water will match on the string Fetch a pail of water.

  • Strings embedded in other strings are ignored during the matching process.

  • In words that have dashes, the parts separated by dashes are treated as distinct words.

Example: If the anchor string is forget, then an anchor tab is placed on the forget in forget-me-not, even when anchorMatchWholeWord is set to true.

  • Letters with accent marks are treated as distinct characters from their unaccented counterparts.

  • For single-character anchor strings, if the two characters appear next to each other in the document, a single anchor tab is placed for both of them.

Example: If the anchor string is i, then only one anchor tab is placed in skiing.

  • Unlike punctuation, numbers are not ignored when finding anchor words.

Example: If the anchor string is cat, then -cat- is matched, but 1cat2 is not when anchorMatchWholeWord is set to true (its default value).

Note: You can only specify the value of this property in POST requests.

anchorUnitsstringOptional

Specifies units of the anchorXOffset and anchorYOffset. Valid units are:

  • pixels (default)
  • inches
  • mms
  • cms
anchorXOffsetstringOptional
Specifies the X axis location of the tab, in anchorUnits, relative to the anchorString.
anchorYOffsetstringOptional
Specifies the Y axis location of the tab, in anchorUnits, relative to the anchorString.
boldstringOptional

When true, the information in the tab is bold.

collaborativestringOptional

When true, the tab can be edited by any recipient during signing.

concealValueOnDocumentstringOptional

When true, the field appears normally while the recipient is adding or modifying the information in the field, but the data is not visible (the characters are hidden by asterisks) to any other signer or the sender.

When an envelope is completed, the information is only available to the sender through the Form Data link in the Docusign console. The information on the downloaded document remains masked by asterisks.

This setting applies only to text boxes and does not affect list boxes, radio buttons, or check boxes.

createdByDisplayNamestringOptional
The user name of the DocuSign user who created this object.
createdByUserIdstringOptional
The userId of the DocuSign user who created this object.
customTabIdstringOptional
The DocuSign generated custom tab ID for the custom tab to be applied. This can only be used when adding new tabs for a recipient. When used, the new tab inherits all the custom tab properties.
disableAutoSizestringOptional

When true, disables the auto-sizing of single-line text boxes in the signing screen when the signer enters data. If auto-sizing is disabled, users will only be able enter as much data as the text box can hold. By default this is false. This property only affects single-line text boxes.

editablestringOptional

When true, the custom tab is editable. Otherwise the custom tab cannot be modified.

fontstringOptional

The font to be used for the tab value. Supported fonts include:

  • Default
  • Arial
  • ArialNarrow
  • Calibri
  • CourierNew
  • Garamond
  • Georgia
  • Helvetica
  • LucidaConsole
  • MSGothic
  • MSMincho
  • OcrA (OCR-A)
  • Tahoma
  • TimesNewRoman
  • Trebuchet
  • Verdana
fontColorstringOptional

The font color to use for the information in the tab. Possible values are:

  • Black
  • BrightBlue
  • BrightRed
  • DarkGreen
  • DarkRed
  • Gold
  • Green
  • NavyBlue
  • Purple
  • White
fontSizestringOptional

The font size used for the information in the tab. Possible values are:

  • Size7
  • Size8
  • Size9
  • Size10
  • Size11
  • Size12
  • Size14
  • Size16
  • Size18
  • Size20
  • Size22
  • Size24
  • Size26
  • Size28
  • Size36
  • Size48
  • Size72
heightstringOptional
The height of the tab in pixels. Must be an integer.
includedInEmailstringOptional

When true, the tab is included in emails related to the envelope on which it exists. This applies to only specific tabs.

initialValuestringOptional
The original value of the tab.
italicstringOptional

When true, the information in the tab is italic.

itemslist of stringsOptional
If the tab is a list, this represents the values that are possible for the tab.
lastModifiedstringOptional
The UTC DateTime this object was last modified. This is in ISO8601 format.
lastModifiedByDisplayNamestringOptional
The User Name of the DocuSign user who last modified this object.
lastModifiedByUserIdstringOptional
The userId of the DocuSign user who last modified this object.
localePolicyobjectOptional
Allows you to customize locale settings.
lockedstringOptional

When true, the signer cannot change the data of the custom tab.

maximumLengthstringOptional
The maximum number of entry characters supported by the custom tab.
maxNumericalValuestringOptional
mergeFieldobjectOptional
Contains information for transferring values between Salesforce data fields and Docusign tabs.
minNumericalValuestringOptional
namestringOptional
numericalValuestringOptional
paymentItemCodestringOptional

If the custom tab is for a payment request, this is the external code for the item associated with the charge. For example, this might be your product id.

Example: SHAK1

Maximum Length: 100 characters.

paymentItemDescriptionstringOptional

If the custom tab is for a payment request, this is the description of the item associated with the charge.

Example: The Danish play by Shakespeare

Maximum Length: 100 characters.

paymentItemNamestringOptional

If the custom tab is for a payment request, this is the name of the item associated with the charge.

Maximum Length: 100 characters.

Example: Hamlet

requireAllstringOptional

When true and shared is true, information must be entered in this field to complete the envelope.

requiredstringOptional

When true, the signer is required to fill out this tab.

requireInitialOnSharedChangestringOptional

Optional element for field markup. When true, the signer is required to initial when they modify a shared field.

scaleValuestringOptional

Sets the size of the tab. This field accepts values from 0.5 to 1.0, where 1.0 represents full size and 0.5 is 50% of full size.

selectedstringOptional

When true, the radio button is selected.

sharedstringOptional

When true, the tab is shared with all users on the account.

signatureProviderIdstringOptional
Reserved for Docusign.
stampTypestringOptional

The type of stamp. Valid values are:

  • signature: A signature image. This is the default value.
  • stamp: A stamp image.
  • null
stampTypeMetadataobjectOptional
Metadata about a property.
tabLabelstringOptional

The 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.

typestringOptional

The type of this tab. Values are:

  • Approve
  • CheckBox
  • Company
  • Date
  • DateSigned
  • Decline
  • Email
  • EmailAddress
  • EnvelopeId
  • FirstName
  • Formula
  • FullName
  • InitialHere
  • InitialHereOptional
  • LastName
  • List
  • Note
  • Number
  • Radio
  • SignerAttachment
  • SignHere
  • SignHereOptional
  • Ssn
  • Text
  • Title
  • Zip5
  • Zip5Dash4
underlinestringOptional

When true, the information in the tab is underlined.

validationMessagestringOptional

The message displayed if the custom tab fails input validation (either custom or embedded).

validationPatternstringOptional
A regular expression used to validate input for the tab.
validationTypestringOptional

Specifies how numerical data is validated. Valid values:

  • number
  • currency
widthstringOptional
The width of the tab in pixels. Must be an integer.

Errors

400
Bad Request Error