Docusign ConnectConfigurations API

openapi: 3.2.0
info:
  title: DocuSign REST Connect Configurations 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: ConnectConfigurations
  description: The ConnectConfigurations resource methods enable you to configure the DocuSign Connect service associated with an account.
paths:
  /v2/accounts/{accountId}/connect:
    get:
      tags:
      - ConnectConfigurations
      summary: Docusign Get Connect Configuration Information
      description: 'Retrieves all the DocuSign Custom Connect definitions for the specified account.


        ###### Note: Connect must be enabled for your account to use this function. This does not retrieve information for Connect configurations for Box, eOriginal, or Salesforce.'
      operationId: Connect_GetConnectConfigs
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/connectConfigResults'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: listConfigurations
      x-ds-method: list
      x-ds-service: Connect
      x-ds-in-sdk: true
    put:
      tags:
      - ConnectConfigurations
      summary: Docusign Updates a specified Connect configuration.
      description: 'Updates the specified DocuSign Connect configuration in your account.


        ###### Note: Connect must be enabled for your account to use this function. This cannot be used to update Connect configurations for Box, eOriginal, or Salesforce.'
      operationId: Connect_PutConnectConfiguration
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connectCustomConfiguration'
          application/xml:
            schema:
              $ref: '#/components/schemas/connectCustomConfiguration'
        required: false
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/connectCustomConfiguration'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: updateConfiguration
      x-ds-method: update
      x-ds-service: Connect
      x-ds-in-sdk: true
      x-codegen-request-body-name: connectCustomConfiguration
    post:
      tags:
      - ConnectConfigurations
      summary: Docusign Creates a connect configuration for the specified account.
      description: 'Creates a DocuSign Custom Connect definition for your account. DocuSign Connect enables the sending of real-time data updates to external applications. These updates are generated by user transactions as the envelope progresses through actions to completion. The Connect Service provides updated information about the status of these transactions and returns updates that include the actual content of document form fields. Be aware that, these updates might or might not include the document itself. For more information about Connect, see the [ML:DocuSign Connect Service Guide].


        ###### Note: Connect must be enabled for your account to use this function. This cannot be used to set up Connect configurations for Salesforce or eOriginal.'
      operationId: Connect_PostConnectConfiguration
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connectCustomConfiguration'
          application/xml:
            schema:
              $ref: '#/components/schemas/connectCustomConfiguration'
        required: false
      responses:
        '201':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/connectCustomConfiguration'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: createConfiguration
      x-ds-method: create
      x-ds-service: Connect
      x-ds-in-sdk: true
      x-codegen-request-body-name: connectCustomConfiguration
  /v2/accounts/{accountId}/connect/{connectId}:
    get:
      tags:
      - ConnectConfigurations
      summary: Docusign Get information on a Connect Configuration
      description: 'Retrieves the information for the specified DocuSign Connect configuration.


        ###### Note: Connect must be enabled for your account to use this function.

        '
      operationId: Connect_GetConnectConfig
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: connectId
        in: path
        description: The ID of the custom Connect configuration being accessed.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/connectConfigResults'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: getConfiguration
      x-ds-method: get
      x-ds-service: Connect
      x-ds-in-sdk: true
    delete:
      tags:
      - ConnectConfigurations
      summary: Docusign Deletes the specified connect configuration.
      description: "Deletes the specified DocuSign Connect configuration.\n\n###### Note: Connect must be enabled for your account to use this function.\n\n \n"
      operationId: Connect_DeleteConnectConfig
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: connectId
        in: path
        description: The ID of the custom Connect configuration being accessed.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content: {}
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: deleteConfiguration
      x-ds-method: delete
      x-ds-service: Connect
      x-ds-in-sdk: true
  /v2/accounts/{accountId}/connect/{connectId}/users:
    get:
      tags:
      - ConnectConfigurations
      summary: Docusign Returns users from the configured Connect service.
      description: Returns users from the configured Connect service.
      operationId: Connect_GetConnectUsers
      parameters:
      - name: accountId
        in: path
        description: The external account number (int) or account id GUID.
        required: true
        schema:
          type: string
      - name: connectId
        in: path
        description: The ID of the custom Connect configuration being accessed.
        required: true
        schema:
          type: string
      - name: count
        in: query
        description: 'Optional. Number of items to return.

          '
        schema:
          type: string
      - name: email_substring
        in: query
        description: Filters the returned user records by the email address or a sub-string of email address.
        schema:
          type: string
      - name: list_included_users
        in: query
        schema:
          type: string
      - name: start_position
        in: query
        description: The position within the total result set from which to start returning values. The value **thumbnail** may be used to return the page image.
        schema:
          type: string
      - name: status
        in: query
        description: "Filters the results by user status.\nYou can specify a comma-separated\nlist of the following statuses:\n\n* ActivationRequired \n* ActivationSent \n* Active\n* Closed \n* Disabled\n"
        schema:
          type: string
      - name: user_name_substring
        in: query
        description: Filters the user records returned by the user name or a sub-string of user name.
        schema:
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/integratedUserInfoList'
        '400':
          description: Error encountered.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/errorDetails'
      deprecated: false
      x-ds-methodname: connectUsers
      x-ds-method: listUsers
      x-ds-service: Connect
      x-ds-in-sdk: true
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.
    connectCustomConfiguration:
      type: object
      properties:
        allowEnvelopePublish:
          type: string
          description: When set to **true**, data is sent to the urlToPublishTo web address. This option can be set to false to stop sending data while maintaining the Connect configuration information.
        allUsers:
          type: string
          description: When set to **true**, the tracked envelope and recipient events for all users, including users that are added a later time, are sent through Connect.
        configurationType:
          type: string
          description: If merge field's are being used, specifies the type of the merge field. The only  supported value is **salesforce**.
        connectId:
          type: string
          description: The ID of the custom Connect configuration being accessed.
        enableLog:
          type: string
          description: This turns Connect logging on or off. When set to **true**, logging is turned on.
        envelopeEvents:
          type: string
          description: "A list of envelope-level event statuses that will trigger Connect to send updates to the endpoint specified in the `url` property. \n\nTo receive notifications, you must include either an `envelopeEvents` node or a `recipientEvents` node. You do not need to specify both."
        includeCertificateOfCompletion:
          type: string
          description: 'When set to **true**, the Connect Service includes the Certificate of Completion with completed envelopes. '
        includeCertSoapHeader:
          type: string
          description: ''
        includeDocumentFields:
          type: string
          description: 'When set to **true**, the Document Fields associated with the envelope''s documents are included in the notification messages. Document Fields are optional custom name-value pairs added to documents using the API. '
        includeDocuments:
          type: string
          description: reserved
        includeEnvelopeVoidReason:
          type: string
          description: 'When set to **true**, if the envelope is voided, the Connect Service notification will include the void reason, as entered by the person that voided the envelope. '
        includeHMAC:
          type: string
          description: ''
        includeSenderAccountasCustomField:
          type: string
          description: When set to **true**, Connect will include the sender account as Custom Field in the data.
        includeTimeZoneInformation:
          type: string
          description: When set to **true**, Connect will include the envelope time zone information.
        name:
          type: string
          description: ''
        recipientEvents:
          type: string
          description: "An array of recipient event statuses that will trigger Connect to send notifications to your webhook listener at the url endpoint specified in the `url` property. \n\nTo receive notifications, you must include either an `envelopeEvents` node or a `recipientEvents` node. You do not need to specify both."
        requiresAcknowledgement:
          type: string
          description: "#### When set to **true**, and SIM mode is activated:\n\nIf the HTTP Status response to a notification message is not in the range of 200-299 then the message delivery failed, and the configuration is marked as *down.*\n\nThe message will be queued and retried once per day. While a Connect configuration is marked down, subsequent notifications will not be tried, they'll be immediately queued with reason \"Pending.\" Once a message succeeds, all queued messages for the configuration will be tried immediately, in order.\n\nThere is a maximum of ten retries Alternately, you can use Republish Connect Information to manually republish the notification.\n\n#### When set to **true**, and SIM mode is not activated: \n\nIf the HTTP Status response to a notification message is not in the range of 200-299 then the message delivery failed, and the message is queued.\n\nThe message will be retried after at least a day the next time a subsequent message is successfully sent to this configuration (subscription).  Subsequent notifications will be tried when they occur.\nThere is a maximum of ten retries Alternately, you can use Republish Connect Information to manually republish the notification."
        signMessageWithX509Certificate:
          type: string
          description: 'When set to **true**, Mutual TLS will be enabled for notifications. Mutual TLS must be initiated by the listener (the customer''s web server) during the TLS handshake protocol. '
        soapNamespace:
          type: string
          description: 'The namespace of the SOAP interface.


            The namespace value must be set if useSoapInterface is set to true.'
        urlToPublishTo:
          type: string
          description: This is the web address and name of your listener or Retrieving Service endpoint. You need to include HTTPS:// in the web address.
        userIds:
          type: string
          description: "A comma separated list of userIds. This sets the users associated with the tracked envelope and recipient events. When a tracked event occurs for a set user, the a notification message is sent to your Connect listener. \n\n###### Note: If allUsers is set to `false` then you must provide a list of user ids."
        useSoapInterface:
          type: string
          description: 'When set to **true**, the notifications are sent to your endpoint as SOAP requests. '
      description: ''
      x-ds-definition-name: connectCustomConfiguration
      x-ms-summary: ''
    userInfo:
      type: object
      properties:
        activationAccessCode:
          type: string
          description: ''
        email:
          type: string
          description: ''
        errorDetails:
          $ref: '#/components/schemas/errorDetails'
        loginStatus:
          type: string
          description: ''
        sendActivationEmail:
          type: string
          description: ''
        uri:
          type: string
          description: ''
        userId:
          type: string
          description: 'The user ID of the user being accessed. Generally this is the user ID of the authenticated user, but if the authenticated user is an Admin on the account, this may be another user the Admin user is accessing. **Note**: For the [GET /v2/accounts/{accountId}/envelopes](https://developers.docusign.com/esign-rest-api/reference/Envelopes/Envelopes/listStatusChanges/#envelopesInformation) method, the `user_id` query parameter is not implemented and should not be used.'
        userName:
          type: string
          description: ''
        userStatus:
          type: string
          description: 'Status of the user''s account. One of:


            * ActivationRequired

            * ActivationSent

            * Active

            * Closed

            * Disabled

            '
        userType:
          type: string
          description: ''
      description: ''
      x-ds-definition-name: userInfo
      x-ms-summary: ''
    integratedUserInfoList:
      type: object
      properties:
        allUsersSelected:
          type: string
          description: ''
        endPosition:
          type: string
          description: 'The last position in the result set. '
        nextUri:
          type: string
          description: 'The 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. '
        previousUri:
          type: string
          description: 'The 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. '
        resultSetSize:
          type: string
          description: 'The number of results returned in this response. '
        startPosition:
          type: string
          description: Starting position of the current result set.
        totalSetSize:
          type: string
          description: The total number of items in the search's result set. It will always be greater than or equal to the value of the `resultSetSize` field.
        users:
          type: array
          description: ''
          items:
            $ref: '#/components/schemas/userInfo'
      description: ''
      x-ds-definition-name: integratedUserInfoList
      x-ms-summary: ''
    connectConfigResults:
      type: object
      properties:
        configurations:
          type: array
          description: Array of Connect Configurations
          items:
            $ref: '#/components/schemas/connectCustomConfiguration'
        totalRecords:
          type: string
          description: Record count.
      description: ''
      x-ds-definition-name: connectConfigResults
      x-ms-summary: ''
externalDocs:
  description: See the DocuSign REST API Guide for more information.
  url: https://docs.docusign.com/esign
x-ds-allow-editing: false
x-ds-categories:
- name: Authentication
  summary: Logging in and authentication
  description: 'Use the Authentication category to manage various account login tasks including:


    * Getting login information for a user.

    * Managing linked social accounts.

    * Getting and revoking OAuth tokens.'
- name: Envelopes
  summary: Creating and sending envelopes
  description: 'The DocuSign API Envelope category includes the resources and methods for sending and managing envelopes and envelope data.


    Envelopes are the key objects within the DocuSign eSignature system. As a result, they are complex data structures with few required fields. See the [API Recipes](https://www.docusign.com/developer-center/recipes) for use case examples and their solutions.


    To create and send envelopes, see the [Envelopes resource](Envelopes).


    '
- name: Connect
  summary: Connect configuration and logging
  description: "The Connect category enables your application to be called via HTTPS when an event of interest occurs.\n\nUse the Connect service to \"end the polling madness.\" With Connect, there is no need for your application to poll DocuSign every 15 minutes to learn the latest about your envelopes.\n\nInstead, you register your interest in one or more types of envelope or recipient events. Then, when an interesting event occurs, the DocuSign platform will contact your application with the event's details and data. You can register interest in envelopes sent by particular users in your account, or for envelopes sent by any user.\n\n## Incoming Connect Calls\nTo use the Connect service, your application needs to provide an https url that can be called from the public internet. If your application runs on a server behind your organization's firewall, then you will need to create a \"pinhole\" in the firewall to allow the incoming Connect calls from DocuSign to reach your application. Other techniques for receiving the incoming calls including proxy servers and DMZ networking can also be used. \n\n## Per-envelope Connect Configuration\nInstead of registering a general Connect configuration and listener, an individual envelope can have its own Connect configuration. See the `eventNotification` field for envelopes.\n\n## Categories\nUse the Connect category for:\n\n* Programmatically creating Connect configurations. Connect configurations can be created manually by using the DocuSign web service, or programmatically via the API. Configurations created via the API can be seen and updated from the web service.\n* Retrieving and managing the event log for your Connect configurations. \n* Requesting that an event be re-published to the listener."
- name: Templates
  summary: Template creation and management
  description: 'Use the Templates category to manage your account''s templates.


    You can:


    * Create, list, get, update, and delete templates.

    * Manage templates'' notification and group sharing settings.

    * Fetch and rotate pages from a document used by a template.


    Templates can be created programmatically or can be created via the DocuSign web interface and then used by your application.'
- name: SigningGroups
  summary: Send a signing request to a group of potential signers
  description: 'Use the SigningGroup category to manage signing groups that allow you anyone in the group to sign a document.


    The category allows you create the signing group and manage the users in the group.'
- name: Folders
  summary: Folders for completed envelopes
  description: "Use the Folders category to manage envelopes in your folders. \n\nYou can list the folder contents and move envelopes between folders."
- name: CustomTabs
  summary: Custom tabs
  description: "Custom Tabs enable accounts to have one or more pre-configured (custom) tabs. Custom tabs save time when users are tagging documents since the users don't have to manually set the tabs' parameters.\n\nThis category enables custom tabs to be managed programmatically, including creation, deletion, etc. \n"
- name: CloudStorage
  summary: Cloud storage providers and user management
  description: 'Use the Cloud Storage category to list the user''s cloud storage document contents.


    It is also used to manage the user''s authentication/accounts with cloud storage service providers.'
- name: Users
  summary: User management
  description: 'Use the Users category to manage the users in your accounts.


    You can:


    * Set custom user settings.

    * Manage a users profile.

    * Add delete users.

    * Add and delete the intials and signature images for a user.'
- name: UserGroups
  summary: Group users for common permissions and branding
  description: 'Use the User Groups category to manage your permissions groups.


    You can:


    * Create and delete groups.

    * Add users to, and delete users from, your groups.

    * Manage the brand information associated with a group.'
- name: Accounts
  summary: Account management
  description: "Use the Account category for various account management tasks including:\n\n* Programmatically creating and deleting accounts.\n* Getting information about an account and its capabilities.\n* Branding the account with custom colors, message text, and more.\n* Account charges.\n\nThe Account category also includes end points for \n* Listing the recipient names associated with an email address that was used by the account. For example, a single email address is often shared by mulitple members of a family.\n\n\n"
- name: Billing
  summary: Invoices
  description: 'Use the Billing category to manage the following billing related tasks:


    * Retrieve and update billing plan information.

    * Retrieve invoices.

    * Retrieve and update payment information.'
- name: Diagnostics
  summary: Diagnostics and request logging
  description: 'The Diagnostics category provides miscellaneous end points.


    They include:

    * Requesting and managing the API call-logging feature. (Perfect for debugging your app!)

    * Getting information on the API''s resources and versions.'
- name: PowerForms
  summary: PowerForm creation and management
  description: The PowerForms category enables PowerForms to be created and managed.
- name: Workspaces
  summary: Workspace creation and management
  description: 'Workspaces creation and management.


    '
- name: Payments
  summary: Manage Payments
  description: This category includes resources for managing payment gateways. Payment information is added to envelopes via methods in the Envelopes category.
- name: Signature
  summary: ''
  description: ''
x-original-swagger-version: '2.0'