Docusign TemplateDocuments API

openapi: 3.2.0
info:
  title: DocuSign REST Template Documents API
  description: The DocuSign REST API provides you with a powerful, convenient, and simple Web services API for interacting with DocuSign.
  termsOfService: https://www.docusign.com/company/terms-and-conditions/web
  contact:
    name: DocuSign Developer Center
    url: https://developers.docusign.com/
    email: devcenter@docusign.com
  version: v2
servers:
- url: https://www.docusign.net/restapi
tags:
- name: TemplateDocuments
  description: "<!-- resources aren't rendered the same way\n     as other pages. This is a little hack to\n     make the headings work better -->\n<style>\nh1, h2, h3 {\n  margin-top: 1em;\n}\n</style>\n\nThe TemplateDocuments resource provides methods\nthat manage documents in a template.\nYou can:\n* add one or more documents to the template\n* retrieve one or more documents from the template\n* delete documents from the template\n\nAll of the methods in this resource\noperate on on an existing template.\nBefore you can add documents\nto a template,\nyou must first create it\nwith the [Templates: create][templatescreate] method. \n\n[templatescreate]: https://developers.docusign.com/esign-rest-api/reference/Templates/Templates/create/\n"
paths:
  /v2/accounts/{accountId}/templates/{templateId}/documents:
    get:
      tags:
      - TemplateDocuments
      summary: Docusign Gets a list of documents associated with a template.
      description: Retrieves a list of documents associated with the specified template.
      operationId: Documents_GetTemplateDocuments
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: templateId
        in: path
        description: The ID of the template being accessed.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/templateDocumentsResult'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: listDocuments
      x-ds-method: list
      x-ds-service: Templates
      x-ds-in-sdk: true
    put:
      tags:
      - TemplateDocuments
      summary: Docusign Adds documents to a template document.
      description: Adds one or more documents to an existing template document.
      operationId: Documents_PutTemplateDocuments
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: templateId
        in: path
        description: The ID of the template being accessed.
        required: true
        schema:
          type: string
      - name: apply_document_fields
        in: query
        description: 'When **true**, document fields

          can be added or modified

          while adding or modifying envelope documents.

          '
        schema:
          type: string
      - name: persist_tabs
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
          application/xml:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
        required: false
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/templateDocumentsResult'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: updateDocuments
      x-ds-method: updateList
      x-ds-service: Templates
      x-ds-in-sdk: true
      x-codegen-request-body-name: envelopeDefinition
    delete:
      tags:
      - TemplateDocuments
      summary: Docusign Deletes documents from a template.
      description: Deletes one or more documents from an existing template.
      operationId: Documents_DeleteTemplateDocuments
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: templateId
        in: path
        description: The ID of the template being accessed.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
          application/xml:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
        required: false
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/templateDocumentsResult'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: deleteDocuments
      x-ds-method: delete
      x-ds-service: Templates
      x-ds-in-sdk: true
      x-codegen-request-body-name: envelopeDefinition
  /v2/accounts/{accountId}/templates/{templateId}/documents/{documentId}:
    get:
      tags:
      - TemplateDocuments
      summary: Docusign Gets PDF documents from a template.
      description: 'Retrieves one or more PDF documents from the specified template.


        You can specify the ID of the document to retrieve or can specify `combined` to retrieve all documents in the template as one pdf.'
      operationId: Documents_GetTemplateDocument
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: documentId
        in: path
        description: The ID of the document being accessed.
        required: true
        schema:
          type: string
      - name: templateId
        in: path
        description: The ID of the template being accessed.
        required: true
        schema:
          type: string
      - name: encrypt
        in: query
        schema:
          type: string
      - name: show_changes
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Error encountered.
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: getDocument
      x-ds-method: get
      x-ds-service: Templates
      x-ds-in-sdk: true
    put:
      tags:
      - TemplateDocuments
      summary: Docusign Adds a document to a template document.
      description: Adds the specified document to an existing template document.
      operationId: Documents_PutTemplateDocument
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: documentId
        in: path
        description: The ID of the document being accessed.
        required: true
        schema:
          type: string
      - name: templateId
        in: path
        description: The ID of the template being accessed.
        required: true
        schema:
          type: string
      - name: apply_document_fields
        in: query
        description: 'When **true**, document fields

          can be added or modified

          while adding or modifying envelope documents.

          '
        schema:
          type: string
      - name: is_envelope_definition
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
          application/xml:
            schema:
              $ref: '#/components/schemas/envelopeDefinition'
        required: false
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/envelopeDocument'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: updateDocument
      x-ds-method: update
      x-ds-service: Templates
      x-ds-in-sdk: true
      x-codegen-request-body-name: envelopeDefinition
components:
  schemas:
    addressInformationInput:
      type: object
      properties:
        addressInformation:
          $ref: '#/components/schemas/addressInformation'
        displayLevelCode:
          type: string
          description: "Specifies the display level for the recipient. \nValid values are: \n\n* ReadOnly\n* Editable\n* DoNotDisplay"
        receiveInResponse:
          type: string
          description: When set to **true**, the information needs to be returned in the response.
      description: Contains address input information.
      x-ds-definition-name: addressInformationInput
      x-ms-summary: Contains address input information.
    recipientPhoneAuthentication:
      type: object
      properties:
        recipMayProvideNumber:
          type: string
          description: Boolean. When set to **true**, the recipient can supply a phone number their choice.
        recordVoicePrint:
          type: string
          description: Reserved.
        senderProvidedNumbers:
          type: array
          description: 'An Array containing a list of phone numbers the recipient may use for SMS text authentication. '
          items:
            type: string
        validateRecipProvidedNumber:
          type: string
          description: ' Reserved.'
      description: 'A complex type that Contains the elements:


        * recipMayProvideNumber - Boolean. When set to **true**, the recipient can use whatever phone number they choose.

        * senderProvidedNumbers - ArrayOfString.  A list of phone numbers the recipient can use.

        * recordVoicePrint - Reserved.

        * validateRecipProvidedNumber - Reserved.'
      x-ds-definition-name: recipientPhoneAuthentication
      x-ms-summary: 'A complex type that Contains the elements:


        * recipMayProvideNumber - Boolean. When set to **true**, the recipient can use whatever phone number they choose.

        * senderProvidedNumbers - ArrayOfString.  A list of phone numbers the recipient can use.

        * recordVoicePrint - Reserved.

        * validateRecipProvidedNumber - Reserved.'
    recipientIdentityPhoneNumber:
      type: object
      properties:
        countryCode:
          type: string
          description: ''
        extension:
          type: string
          description: ''
        number:
          type: string
          description: ''
      description: ''
      x-ds-definition-name: recipientIdentityPhoneNumber
      x-ms-summary: ''
    fullName:
      type: object
      properties:
        anchorCaseSensitive:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            When set to **true**, the anchor string does not consider case when matching strings in the document. The default value is **true**.

            -->'
        anchorHorizontalAlignment:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            Specifies the alignment of anchor tabs with anchor strings. Possible values are **left** or **right**. The default value is **left**.

            -->

            '
        anchorIgnoreIfNotPresent:
          type: string
          description: When set to **true**, this tab is ignored if anchorString is not found in the document.
        anchorMatchWholeWord:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            When set to **true**, the anchor string in this tab matches whole words only (strings embedded in other strings are ignored.) The default value is **true**.

            -->

            '
        anchorString:
          type: string
          description: Specifies the anchor string.
        anchorUnits:
          type: string
          description: 'Specifies units of the

            `anchorXOffset` and

            `anchorYOffset`.

            Valid units are:


            - `pixels`

            - `inches`

            - `mms`

            - `cms`

            '
        anchorXOffset:
          type: string
          description: 'Specifies the X axis location of the tab in `anchorUnits` relative to the `anchorString`.

            '
        anchorYOffset:
          type: string
          description: 'Specifies the Y axis location of the tab in `anchorUnits` relative to the `anchorString`.

            '
        bold:
          type: string
          description: When set to **true**, the information in the tab is bold.
        conditionalParentLabel:
          type: string
          description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
        conditionalParentValue:
          type: string
          description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.


            If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.

            '
        customTabId:
          type: string
          description: 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.
        documentId:
          type: string
          description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
        font:
          type: string
          description: 'The font to be used for the tab value. Supported Fonts include:


            - Default

            - Arial

            - ArialNarrow

            - Calibri

            - CourierNew

            - Garamond

            - Georgia

            - Helvetica

            - LucidaConsole

            - MSGothic

            - MSMincho

            - OCR-A

            - Tahoma

            - TimesNewRoman

            - Trebuchet

            - Verdana

            '
        fontColor:
          type: string
          description: "The font color used for the information in the tab. Possible values are: \n\n- Black\n- BrightBlue\n- BrightRed\n- DarkGreen\n- DarkRed\n- Gold\n- Green\n- NavyBlue\n- Purple\n- White\n"
        fontSize:
          type: string
          description: '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'
        italic:
          type: string
          description: When set to **true**, the information in the tab is italic.
        mergeField:
          $ref: '#/components/schemas/mergeField'
        name:
          type: string
          description: ''
        pageNumber:
          type: string
          description: 'Specifies the page number on which the tab is located.

            Must be 1 for supplemental documents.

            '
        recipientId:
          type: string
          description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
        status:
          type: string
          description: 'Tab status

            <!-- todo -->

            '
        tabGroupLabels:
          type: array
          description: ''
          items:
            type: string
        tabId:
          type: string
          description: The unique identifier for the tab.
        tabLabel:
          type: string
          description: 'The label string associated with the tab.

            The string may be the empty string.

            If no value is provided, the tab type is used as the value.


            Maximum of 500 characters.

            '
        tabOrder:
          type: string
          description: 'A positive integer that sets the order the tab is navigated to during signing.


            Tabs on a page are navigated to in ascending order, starting with the lowest number and moving to the highest. If two or more tabs have the same `tabOrder` value, the normal auto-navigation setting behavior for the envelope is used.'
        templateLocked:
          type: string
          description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
        templateRequired:
          type: string
          description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
        tooltip:
          type: string
          description: ''
        underline:
          type: string
          description: When set to **true**, the information in the tab is underlined.
        value:
          type: string
          description: 'Specifies the value of the tab. '
        xPosition:
          type: string
          description: 'This property indicates the horizontal offset of the object on the page.

            DocuSign uses 72 DPI when determining position.

            Required. May be zero.


            To improve the tab''s position on the document,

            DocuSign recommends

            adjusting `xPosition`

            and `yPosition`

            coordinates

            by (-3, -2)

            '
        yPosition:
          type: string
          description: 'This property indicates the vertical offset of the object on the page.

            DocuSign uses 72 DPI when determining position.

            Required. May be zero.


            To improve the tab''s position on the document,

            DocuSign recommends

            adjusting `xPosition`

            and `yPosition`

            coordinates

            by (-3, -2)

            '
      description: 'A tab that displays the recipient''s full name.

        '
      x-ds-definition-name: fullName
      x-ms-summary: 'A tab that displays the recipient''s full name.

        '
    textCustomField:
      type: object
      properties:
        configurationType:
          type: string
          description: If merge field's are being used, specifies the type of the merge field. The only  supported value is **salesforce**.
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
        fieldId:
          type: string
          description: An ID used to specify a custom field.
        name:
          type: string
          description: The name of the custom field.
        required:
          type: string
          description: When set to **true**, the signer is required to fill out this tab
        show:
          type: string
          description: 'A boolean indicating if the value should be displayed.  If this value is set to **true**, the custom field is displayed at the top of the certificate of completion. If this value is left blank/ or set to **false**, then it does not appear in the certificate of completion. '
        value:
          type: string
          description: The value of the custom field.
      description: ''
      x-ds-definition-name: textCustomField
      x-ms-summary: ''
    number:
      type: object
      properties:
        anchorCaseSensitive:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            When set to **true**, the anchor string does not consider case when matching strings in the document. The default value is **true**.

            -->'
        anchorHorizontalAlignment:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            Specifies the alignment of anchor tabs with anchor strings. Possible values are **left** or **right**. The default value is **left**.

            -->

            '
        anchorIgnoreIfNotPresent:
          type: string
          description: When set to **true**, this tab is ignored if anchorString is not found in the document.
        anchorMatchWholeWord:
          type: string
          description: 'Reserved for DocuSign.

            <!--

            When set to **true**, the anchor string in this tab matches whole words only (strings embedded in other strings are ignored.) The default value is **true**.

            -->

            '
        anchorString:
          type: string
          description: Specifies the anchor string.
        anchorUnits:
          type: string
          description: 'Specifies units of the

            `anchorXOffset` and

            `anchorYOffset`.

            Valid units are:


            - `pixels`

            - `inches`

            - `mms`

            - `cms`

            '
        anchorXOffset:
          type: string
          description: 'Specifies the X axis location of the tab in `anchorUnits` relative to the `anchorString`.

            '
        anchorYOffset:
          type: string
          description: 'Specifies the Y axis location of the tab in `anchorUnits` relative to the `anchorString`.

            '
        bold:
          type: string
          description: When set to **true**, the information in the tab is bold.
        concealValueOnDocument:
          type: string
          description: 'When set to **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 available to the sender through the Form Data link in the DocuSign Console.


            This setting applies only to text boxes and does not affect list boxes, radio buttons, or check boxes.'
        conditionalParentLabel:
          type: string
          description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
        conditionalParentValue:
          type: string
          description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.


            If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.

            '
        customTabId:
          type: string
          description: 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.
        disableAutoSize:
          type: string
          description: When set to **true**, disables the auto sizing of single line text boxes in the signing screen when the signer enters data. If 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.
        documentId:
          type: string
          description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
        font:
          type: string
          description: 'The font to be used for the tab value. Supported Fonts include:


            - Default

            - Arial

            - ArialNarrow

            - Calibri

            - CourierNew

            - Garamond

            - Georgia

            - Helvetica

            - LucidaConsole

            - MSGothic

            - MSMincho

            - OCR-A

            - Tahoma

            - TimesNewRoman

            - Trebuchet

            - Verdana

            '
        fontColor:
          type: string
          description: "The font color used for the information in the tab. Possible values are: \n\n- Black\n- BrightBlue\n- BrightRed\n- DarkGreen\n- DarkRed\n- Gold\n- Green\n- NavyBlue\n- Purple\n- White\n"
        fontSize:
          type: string
          description: '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'
        formula:
          type: string
          description: 'Contains the formula

            for calculating the value of

            this tab.


            Use a tab''s `tabLabel`,

            enclosed in brackets,

            to refer to it.


            For example,

            you want to present the total cost

            of two items, tax included.


            The cost of each item is stored

            in number tabs labeled Item1 and Item2.

            The tax rate is in a number tab

            labeled TaxRate.


            The formula string for this property

            would be:

            `([Item1] + [Item2]) * (1 + [TaxRate])`


            See [Calculated Fields][calculatedfields]

            in the DocuSign Support Center

            to learn more about formulas.


            Maximum Length: 2000 characters


            [calculatedfields]: https://support.docusign.com/en/guides/ndse-user-guide-calculated-fields

            '
        isPaymentAmount:
          type: string
          description: 'When set to **true**, sets this as a payment tab. Can only be used with Text, Number, Formula, or List tabs. The value of the tab must be a number. '
        italic:
          type: string
          description: When set to **true**, the information in the tab is italic.
        locked:
          type: string
          description: When set to **true**, the signer cannot change the data of the custom tab.
        maxLength:
          type: integer
          description: An optional value that describes the maximum length of the property when the property is a string.
          format: int32
        mergeField:
          $ref: '#/components/schemas/mergeField'
        name:
          type: string
          description: Specifies the tool tip text for the tab.
        originalValue:
          type: string
          description: 'The initial value of the tab when it was sent to the recipient. '
        pageNumber:
          type: string
          description: 'Specifies the page number on which the tab is located.

            Must be 1 for supplemental documents.

            '
        recipientId:
          type: string
          description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
        requireAll:
          type: string
          description: 'When set to **true** and shared is true, information must be entered in this field to complete the envelope. '
        required:
          type: string
          description: When set to **true**, the signer is required to fill out this tab
        requireInitialOnSharedChange:
          type: string
          description: Optional element for field markup. When set to **true**, the signer is required to initial when they modify a shared field.
        senderRequired:
          type: string
          description: "When set to **true**, the sender must populate the tab before an envelope can be sent using the template. \n\nThis value tab can only be changed by modifying (PUT) the template. \n\nTabs with a `senderRequired` value of true cannot be deleted from an envelope."
        shared:
          type: string
          description: When set to **true**, this custom tab is shared.
        status:
          type: string
          description: 'Tab status

            <!-- todo -->

            '
        tabGroupLabels:
          type: array
          description: ''
          items:
            type: string
        tabId:
          type: string
          description: The unique identifier for the tab.
        tabLabel:
          type: string
          description: 'The label string associated with the tab.

            The string may be the empty string.

            If no value is provided, the tab type is used as the value.


            Maximum of 500 characters.

            '
        tabOrder:
          type: string
          description: 'A positive integer that sets the order the tab is navigated to during signing.


            Tabs on a page are navigated to in ascending order, starting with the lowest number and moving to the highest. If two or more tabs have the same `tabOrder` value, the normal auto-navigation setting behavior for the envelope is used.'
        templateLocked:
          type: string
          description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
        templateRequired:
          type: string
          description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
        tooltip:
          type: string
          description: ''
        underline:
          type: string
          description: When set to **true**, the information in the tab is underlined.
        validationMessage:
          type: string
          description: The message displayed if the custom tab fails input validation (either custom of embedded).
        validationPattern:
          type: string
          description: A regular expressionn used to validate input for the tab.
        value:
          type: string
          description: 'Specifies the value of the tab. '
        width:
          type: integer
          description: Width of the tab in pixels.
          format: int32
        xPosition:
          type: string
          description: 'This property indicates the horizontal offset of the object on the page.

            DocuSign uses 72 DPI when determining position.

            Required. May be zero.


            To improve the tab''s position on the document,

            DocuSign recommends

            adjusting `xPosition`

            and `yPosition`

            coordinates

            by (-3, -2)

            '
        yPosition:
          type: string
          description: 'This property indicates the vertical offset of the object on the page.

            DocuSign uses 72 DPI when determining position.

            Required. May be zero.


            To improve the tab''s position on the document,

            DocuSign recommends

            adjusting `xPosition`

            and `yPosition`

            coordinates

            by (-3, -2)

            '
      description: 'A tab that allows the recipient to enter numbers and decimal

        (.) points.

        '
      x-ds-definition-name: number
      x-ms-summary: 'A tab that allows the recipient to enter numbers and decimal

        (.) points.

        '
    eventResult:
      type: object
      properties:
        eventTimestamp:
          type: string
          description: ''
        failureDescription:
          type: string
          description: ''
        status:
          type: string
          description: Even

# --- truncated at 32 KB (498 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docusign/refs/heads/main/openapi/docusign-templatedocuments-api-openapi.yml