Docusign TemplateViews API

openapi: 3.2.0
info:
  title: Docusign Template Views API
  termsOfService: https://www.docusign.com/company/terms-and-conditions/web
  version: '1.0'
  description: 'Operations tagged TemplateViews across 2 of this provider''s published API definitions: docusign-openapi-original.yml, docusign-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.docusign.net/restapi
tags:
- name: TemplateViews
  description: 'The TemplateViews resource

    provides a method returns a URL

    that you can embed into your application

    to provide access to the DocuSign UI.


    One template view is available:


    * Edit View - the DocuSign UI for editing a template.


    This resource is related to the [EnvelopeViews][envelopeviews] resource.

    Both enable you to embed the DocuSign UI into your application.


    [envelopeviews]: https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeViews/'
paths:
  /v2/accounts/{accountId}/templates/{templateId}/views/edit:
    post:
      tags:
      - TemplateViews
      summary: Docusign Provides a URL to start an edit view of the Template UI
      operationId: Views_PostTemplateEditView
      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/returnUrlRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/returnUrlRequest'
        required: false
      responses:
        '201':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/viewUrl'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: createEditView
      x-ds-method: createEdit
      x-ds-service: Templates
      x-ds-in-sdk: true
      x-codegen-request-body-name: returnUrlRequest
    servers:
    - url: https://www.docusign.net/restapi
  /v2.1/accounts/{accountId}/templates/{templateId}/views/edit:
    parameters: []
    post:
      tags:
      - TemplateViews
      summary: Gets a URL for a template edit view
      operationId: postV21AccountsByAccountIdTemplatesByTemplateIdViewsEdit
      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.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewUrl_2'
        '400':
          description: Error encountered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorDetails_2'
      deprecated: false
      x-ds-methodname: createEditView
      description: 'Returns a URL that enables you to embed the Template Edit view of Docusign eSignature. You can embed the view in an iframe.


        **API request update**


        The API request object for this API method was updated in June 2024. The new API request format is described below. Existing applications must update to the new version: it solves a security issue with the old version. The deprecation schedule was announced in the Docusign Core Release Notes. While backwards compatibility will be provided for a while for existing applications, all applications must be updated to be secure. See below for migration information.


        **Best practices**


        The returned URL expires after 10 minutes. Therefore, request the URL immediately before you redirect your user to it.


        Due to screen space issues, do not use an iframe for embedded operations on mobile devices. For mobile applications, use a WebView (Android) or WKWebView (iOS).


        ### Closing the view''s iframe


        If you choose to embed the view in your application via an iframe, Docusign recommends this software pattern to close the iframe after the view has completed:


        * (One time) create a standalone “return” web page that you will use as the `returnUrl` target for the view. The view will redirect the iframe to this URL when it has completed. Here''s an example return page. In this page, use JavaScript and the postMessage method to send a message to your application with the results of the view.

        * In your application, use `window.addEventListener("message", function_name)` to register a listener for incoming messages.

        * To show the view, use this API method, then set the iframe to load the URL from the API response.

        * In your application, receive the completion message, validate it, and then close the iframe.


        ### Information security


        This view only has write access to the specific template referenced in the API call. The edit access corresponds to the access rights of the user associated with the access token used for the API call.


        **Recommendations:**

        * Use the access token of a service user who can access the template.

        * Do not use the access token of a user with administrator privileges.


        ### Migrating to the current version of the request object


        This section only applies to existing applications that use the older version of the request object.


        Migrating from the old API request object to the new version will take under a day of developer time.


        **Step 1.** Does your application set the returnUrl attribute?


        Yes: continue with step 2.


        No: In this case, your users first edit the template, and then the Docusign eSignature home screen is shown. To accomplish this UI pattern with the new API request format:


        * Set the returnUrl to a new endpoint for your application. You can use query parameters or session data to manage state. Remember to authenticate the incoming requests.

        * When the endpoint is called, use the EnvelopeViews:createConsole API call to obtain and then display the Docusign eSignature home page to your application''s user.


        **Step 2.** Check that these API attributes are set:

        * `"view" = "template" `

        * the `returnUrl` is set.


        **Step 3.** All done! Test your application.'
      x-ds-method: createEdit
      x-ds-service: Templates
      x-ds-in-sdk: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/templateViewRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/templateViewRequest'
      x-operation-id-source: normalized
      x-operation-id-original: Views_PostTemplateEditView
    servers:
    - url: https://www.docusign.net/restapi
components:
  schemas:
    errorDetails:
      type: object
      properties:
        errorCode:
          type: string
          description: An error code associated with the error.
        message:
          type: string
          description: A short error message.
      description: This object describes errors that occur. It is only valid for responses, and ignored in requests.
      x-ds-definition-name: errorDetails
      x-ms-summary: This object describes errors that occur. It is only valid for responses, and ignored in requests.
    returnUrlRequest:
      type: object
      properties:
        returnUrl:
          type: string
          description: "Your app's return url that the user will be redirected to after sending the envelope or completing the sending/tagging view. Query parameters `envelopeId` and `event` will be added to the URL. The event parameter values: \n\n* `Send` (the user sent the envelope)\n* `Save` (the user saved the envelope, it is still a draft)\n* `Cancel` (the user canceled the sending transaction)\n* `Error` (there was an error during the send operation)\n* `SessionEnd` (the sending session ended before the user completed a different action)"
      description: 'The request body for the EnvelopeViews: createSender method.'
      x-ds-definition-name: returnUrlRequest
      x-ms-summary: 'The request body for the EnvelopeViews: createSender method.'
    viewUrl:
      type: object
      properties:
        url:
          type: string
          description: The endpoint to which webhook notification messages are sent via an HTTP/S POST request. For the DocuSign production platform, the url must start with https. For the demo platform, either http or https is ok.
      description: ''
      x-ds-definition-name: viewUrl
      x-ms-summary: ''
    paletteItemSettings:
      type: object
      properties:
        show:
          description: Reserved for Docusign.
          type: string
      x-ds-definition-name: paletteItemSettings
      description: ''
      x-ms-summary: ''
    paletteSettings:
      type: object
      properties:
        annotations:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        custom:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        merge:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        notary:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        seals:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        smartContracts:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
        smartSections:
          $ref: '#/components/schemas/paletteItemSettings'
          description: Reserved for Docusign.
      x-ds-definition-name: paletteSettings
      description: Reserved for Docusign.
      x-ms-summary: Reserved for Docusign.
    envelopeViewEnvelopeCustomFieldSettings:
      type: object
      properties:
        showEnvelopeCustomFields:
          description: Reserved for Docusign.
          type: string
      x-ds-definition-name: envelopeViewEnvelopeCustomFieldSettings
      description: ''
      x-ms-summary: ''
    envelopeViewDocumentSettings:
      type: object
      properties:
        showEditDocuments:
          description: When **false,** prevents the app user from adding, replacing, or deleting documents. The default value is **true.**
          type: string
        showEditDocumentVisibility:
          description: When `false`, prevents the user from modifying document visibility settings. The default value is `true`.
          type: string
        showEditPages:
          description: When `false`, prevents the user from deleting or rotating individual document pages via the thumbnail images. The default value is `true`. If `true` and `showEditDocuments` is `false`, the pages can be rotated but not deleted.
          type: string
        showSaveAsDocumentCustomField:
          description: Reserved for Docusign.
          type: string
      x-ds-definition-name: envelopeViewDocumentSettings
      description: ''
      x-ms-summary: ''
    viewUrl_2:
      type: object
      properties:
        url:
          description: URL for the template edit view.
          type: string
      x-ds-definition-name: viewUrl
      description: ''
      x-ms-summary: ''
    templateViewRequest:
      type: object
      properties:
        returnUrl:
          description: Identifies the return point after the user selects `Save And Close`. This property is required.
          type: string
        settings:
          $ref: '#/components/schemas/templateViewSettings'
          description: Information about the settings for the workspace.
        viewAccess:
          description: 'Set to `template` to limit the app user''s access to only the specified template. **Required.**

            '
          type: string
      x-ds-definition-name: templateViewRequest
      description: ''
      x-ms-summary: ''
    errorDetails_2:
      description: This object describes errors that occur. It is only valid for responses and ignored in requests.
      type: object
      properties:
        errorCode:
          description: The code associated with the error condition.
          type: string
        message:
          description: A brief message describing the error condition.
          type: string
      x-ds-definition-name: errorDetails
      x-ms-summary: This object describes errors that occur. It is only valid for responses and ignored in requests.
    templateViewRecipientSettings:
      type: object
      properties:
        showContactsList:
          description: ''
          type: string
        showEditMessage:
          description: ''
          type: string
        showEditRecipients:
          description: ''
          type: string
      x-ds-definition-name: templateViewRecipientSettings
      description: ''
      x-ms-summary: ''
    templateViewSettings:
      type: object
      properties:
        backButtonAction:
          description: ''
          type: string
        documentSettings:
          $ref: '#/components/schemas/envelopeViewDocumentSettings'
          description: ''
        envelopeCustomFieldSettings:
          $ref: '#/components/schemas/envelopeViewEnvelopeCustomFieldSettings'
          description: ''
        lockToken:
          description: A unique identifier provided to the owner of the lock. You must use this token with subsequent calls to prove ownership of the lock.
          type: string
        recipientSettings:
          $ref: '#/components/schemas/templateViewRecipientSettings'
          description: ''
        showAdvancedOptions:
          description: ''
          type: string
        showBackButton:
          description: ''
          type: string
        showDiscardAction:
          description: ''
          type: string
        showHeaderActions:
          description: ''
          type: string
        startingScreen:
          description: ''
          type: string
        taggerSettings:
          $ref: '#/components/schemas/envelopeViewTaggerSettings'
          description: ''
      x-ds-definition-name: templateViewSettings
      description: ''
      x-ms-summary: ''
    envelopeViewTaggerSettings:
      type: object
      properties:
        paletteDefault:
          description: "When `paletteSections` is set to `custom`, this property selects the default tagger palette. \nValid values:  \n* `custom`\n* `merge`\n* `notary`\n* `seals`\n* `smartContracts`\n* `annotations`\n* `smartSections`"
          type: string
        paletteSections:
          description: 'Valid values:


            * `default` (default): The default tagger palette UX

            * `none`: No tagger palette

            * `custom`: Set by `paletteDefault`'
          type: string
        paletteSettings:
          $ref: '#/components/schemas/paletteSettings'
          description: Reserved for Docusign.
      x-ds-definition-name: envelopeViewTaggerSettings
      description: ''
      x-ms-summary: ''
x-refined-from:
- docusign-openapi-original.yml
- docusign-openapi.json
x-ds-categories:
- name: UserManagement
  summary: Methods to manage users in an account.
  description: Methods to manage users in an account.
- name: BulkOperations
  summary: Methods to import and export users and accounts.
  description: Methods to import and export users and accounts.
- name: IdentityProviders
  summary: Methods to get a list of identity providers.
  description: Methods to get a list of identity providers.
- name: ReservedDomains
  summary: Methods to get a list of reserved domains.
  description: Methods to get a list of reserved domains.
- name: Organization
  summary: Methods for working with organizations.
  description: Methods for working with organizations.
x-original-swagger-version: '2.0'