Accounts: updateSharedAccess

This sets the shared access status for one or more users or templates.

When setting user shared access, only users with account administration privileges can set shared access status for envelopes.

When setting template shared access, only users who own a template and have sharing permission or with account administration privileges can set shared access for templates.

Changes to the shared items status are not additive. The change always replaces the current status.

To change template shared access, add the query parameter item_type = templates to the request. When this is set, the user and envelopes properties are not required.

Note: This functionality is a newer version of the Update Group Share functionality.

Request

HTTP request

PUT /v2.1/accounts/{accountId}/shared_access

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

Optional Query Parameters
item_typestring

Specifies the type of shared item being set:

  • envelopes: Set envelope sharing between users.
  • templates: Set information about template sharing among users and groups.
  • folders: Get information about folder sharing among users and groups.

preserve_existing_shared_accessstring

When true, preserve the existing shared access settings.

user_idsstring

A comma-separated list of IDs for users whose shared item access is being set.

Responses

CodeDescriptionReference
200

Successful response.

accountSharedAccess
400

Error encountered.

errorDetails

SDK Method

Accounts::updateSharedAccess

Definitions

accountSharedAccess

Contains shared access information.

accountIdstring

The account ID associated with the envelope.

endPositionstring

The last index position in the result set.

errorDetailserrorDetails

A complex type containing an errorCode and message identifying the error that occurred.

nextUristring

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.

previousUristring

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.

resultSetSizestring

The number of results in this response. Because you can filter which entries are included in the response, this value is always less than or equal to the totalSetSize.

sharedAccess[memberSharedItems]

A list of shared access information of envelope and templates for the users specified in the request.

startPositionstring

The starting index position of the current result set.

totalSetSizestring

The total number of items in the result set. This value is always greater than or equal to the value of resultSetSize.

errorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

errorCodestring

The code associated with the error condition.

messagestring

A brief message describing the error condition.

folderSharedItem

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

folderIdstring

The id of the folder.

namestring

The name of the folder.

owneruserInfo

Information about the user who owns the folder.

parentFolderIdstring

The id of the parent folder.

parentFolderUristring

The URI for the parent folder.

sharedstring

Indicates how the folder is shared. Valid values are:

  • not_shared
  • shared_to

sharedGroups[memberGroupSharedItem]

A list of groups that share the folder.

sharedUsers[userSharedItem]

A list of users that share the folder.

uristring

A URI containing the user ID.

useruserInfo

Information about the user associated with the folder.

group

This object contains information about a group.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

groupIdstring

The DocuSign group ID for the group.

groupNamestring

The name of the group.

groupTypestring

The group type. Possible values include:

  • adminstrators
  • everyone
  • customGroup
  • sharedSigningGroup

permissionProfileIdstring

The ID of the permission profile associated with the group. Possible values include:

  • 2301416 (for the DocuSign Viewer profile)
  • 2301415 (for the DocuSign Sender profile)
  • 2301414 (for the Account Administrator profile)

users[userInfo]

A list of the users in the group.

usersCountstring

The total number of users in the group.

memberGroupSharedItem

Information about items shared among groups.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

groupgroup

The group sharing the item.

sharedstring

How the item is shared. One of:

  • not_shared: The item is not shared.

  • shared_to: The item is shared.

memberSharedItems

Information about shared items.

envelopes[sharedItem]

List of information about shared envelopes.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

folders[folderSharedItem]

List of information about shared folders.

templates[templateSharedItem]

List of information about shared templates.

useruserInfo

Information about the user requesting sharing information.

sharedItem

Information about the shared item.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

sharedstring

How the item is shared. One of:

  • not_shared
  • shared_to
  • shared_from
  • shared_to_and_from

useruserInfo

Information about the user who owns the shared item.

templateSharedItem

Information about shared templates.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

owneruserInfo

Information about the user who owns the template.

passwordstring

The user's encrypted password hash.

sharedstring

How the template is shared. One of:

  • not_shared
  • shared_to

sharedGroups[memberGroupSharedItem]

List of groups that share the template.

sharedUsers[userSharedItem]

List of users that share the template.

templateIdstring

The unique identifier of the template. If this is not provided, DocuSign will generate a value.

templateNamestring

The name of the shared template.

userInfo

accountIdstring

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

accountNamestring

The name on the account.

activationAccessCodestring

Access code provided to the user to activate the account.

emailstring

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

loginStatusstring

Boolean value that indicates whether the user is currently logged in or not.

membershipIdstring

The user's membership ID.

sendActivationEmailstring

When set to true, specifies that an activation email be sent to the user.

uristring

A URI containing the user ID.

userIdstring

The ID of the user to access. Generally this is the ID of the current authenticated user, but if the authenticated user is an Administrator on the account, userId can represent another user whom the Administrator is accessing.

userNamestring

The name of the user.

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

userTypestring

The type of user, for example CompanyUser.

userSharedItem

Information about a shared item.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

sharedstring

How the item is shared. One of:

  • not_shared
  • shared_to
  • shared_from
  • shared_to_and_from

useruserInfo

The user whose sharing information is being requested.

Examples

Generic JSON Request/Response

Request
{
  "resultSetSize": "sample string 1",
  "totalSetSize": "sample string 2",
  "startPosition": "sample string 3",
  "endPosition": "sample string 4",
  "nextUri": "sample string 5",
  "previousUri": "sample string 6",
  "accountId": "sample string 7",
  "sharedAccess": [
    {
      "user": {
        "userName": "sample string 1",
        "userId": "sample string 2",
        "email": "sample string 3",
        "userType": "sample string 4",
        "userStatus": "sample string 5",
        "uri": "sample string 6",
        "loginStatus": "sample string 7",
        "sendActivationEmail": "sample string 8",
        "activationAccessCode": "sample string 9"
      },
      "envelopes": [
        {
          "user": {},
          "shared": "sample string 1"
        }
      ],
      "templates": [
        {
          "templateId": "sample string 1",
          "templateName": "sample string 2",
          "owner": {},
          "sharedUsers": [
            {
              "user": {}
            }
          ],
          "sharedGroups": [
            {
              "group": {
                "groupId": "sample string 1",
                "groupName": "sample string 2",
                "permissionProfileId": "sample string 3",
                "groupType": "sample string 4",
                "users": [
                  {}
                ]
              }
            }
          ],
          "shared": "sample string 3"
        }
      ]
    }
  ]
}
Response
{
  "resultSetSize": "sample string 1",
  "totalSetSize": "sample string 2",
  "startPosition": "sample string 3",
  "endPosition": "sample string 4",
  "nextUri": "sample string 5",
  "previousUri": "sample string 6",
  "accountId": "sample string 7",
  "sharedAccess": [
    {
      "user": {
        "userName": "sample string 1",
        "userId": "sample string 2",
        "email": "sample string 3",
        "userType": "sample string 4",
        "userStatus": "sample string 5",
        "uri": "sample string 6",
        "loginStatus": "sample string 7",
        "sendActivationEmail": "sample string 8",
        "activationAccessCode": "sample string 9",
        "errorDetails": {
          "errorCode": "sample string 1",
          "message": "sample string 2"
        }
      },
      "envelopes": [
        {
          "user": {},
          "shared": "sample string 1",
          "errorDetails": {
            "errorCode": "SUCCESS",
            "message": ""
          }
        }
      ],
      "templates": [
        {
          "templateId": "sample string 1",
          "templateName": "sample string 2",
          "owner": {},
          "sharedUsers": [
            {
              "user": {},
              "errorDetails": {
                "errorCode": "SUCCESS",
                "message": ""
              },
              "shared": "sample string 1"
            }
          ],
          "sharedGroups": [
            {
              "group": {
                "groupId": "sample string 1",
                "groupName": "sample string 2",
                "permissionProfileId": "sample string 3",
                "groupType": "sample string 4",
                "users": [
                  {}
                ],
                "errorDetails": {
                  "errorCode": "SUCCESS",
                  "message": ""
                }
              },
              "errorDetails": {
                "errorCode": "SUCCESS",
                "message": ""
              },
              "shared": "sample string 1"
            }
          ],
          "errorDetails": {
            "errorCode": "SUCCESS",
            "message": ""
          }
        }
      ],
      "errorDetails": {
        "errorCode": "SUCCESS",
        "message": ""
      }
    }
  ],
  "errorDetails": {
    "errorCode": "SUCCESS",
    "message": ""
  }
}
Generic XML Request/Response

Request
<accountSharedAccess xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <accountId>sample string 7</accountId>
  <endPosition>sample string 4</endPosition>
  <nextUri>sample string 5</nextUri>
  <previousUri>sample string 6</previousUri>
  <resultSetSize>sample string 1</resultSetSize>
  <sharedAccess>
    <memberSharedItems>
      <envelopes>
        <sharedItem>
          <shared>sample string 1</shared>
          <user />
        </sharedItem>
      </envelopes>
      <templates>
        <templateSharedItem>
          <owner />
          <shared>sample string 3</shared>
          <sharedGroups>
            <memberGroupSharedItem>
              <group>
                <groupId>sample string 1</groupId>
                <groupName>sample string 2</groupName>
                <groupType>sample string 4</groupType>
                <permissionProfileId>sample string 3</permissionProfileId>
                <users>
                  <userInfo />
                </users>
              </group>
            </memberGroupSharedItem>
          </sharedGroups>
          <sharedUsers>
            <userSharedItem>
              <user />
            </userSharedItem>
          </sharedUsers>
          <templateId>sample string 1</templateId>
          <templateName>sample string 2</templateName>
        </templateSharedItem>
      </templates>
      <user>
        <activationAccessCode>sample string 9</activationAccessCode>
        <email>sample string 3</email>
        <loginStatus>sample string 7</loginStatus>
        <sendActivationEmail>sample string 8</sendActivationEmail>
        <uri>sample string 6</uri>
        <userId>sample string 2</userId>
        <userName>sample string 1</userName>
        <userStatus>sample string 5</userStatus>
        <userType>sample string 4</userType>
      </user>
    </memberSharedItems>
  </sharedAccess>
  <startPosition>sample string 3</startPosition>
  <totalSetSize>sample string 2</totalSetSize>
</accountSharedAccess> 
Response
<accountSharedAccess xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <accountId>sample string 7</accountId>
  <endPosition>sample string 4</endPosition>
  <errorDetails>
    <errorCode>SUCCESS</errorCode>
    <message></message>
  </errorDetails>
  <nextUri>sample string 5</nextUri>
  <previousUri>sample string 6</previousUri>
  <resultSetSize>sample string 1</resultSetSize>
  <sharedAccess>
    <memberSharedItems>
      <envelopes>
        <sharedItem>
          <errorDetails>
            <errorCode>SUCCESS</errorCode>
            <message></message>
          </errorDetails>
          <shared>sample string 1</shared>
          <user />
        </sharedItem>
      </envelopes>
      <errorDetails>
        <errorCode>SUCCESS</errorCode>
        <message></message>
      </errorDetails>
      <templates>
        <templateSharedItem>
          <errorDetails>
            <errorCode>SUCCESS</errorCode>
            <message></message>
          </errorDetails>
          <owner />
          <sharedGroups>
            <memberGroupSharedItem>
              <errorDetails>
                <errorCode>SUCCESS</errorCode>
                <message></message>
              </errorDetails>
              <group>
                <errorDetails>
                  <errorCode>SUCCESS</errorCode>
                  <message></message>
                </errorDetails>
                <groupId>sample string 1</groupId>
                <groupName>sample string 2</groupName>
                <groupType>sample string 4</groupType>
                <permissionProfileId>sample string 3</permissionProfileId>
                <users>
                  <userInfo />
                </users>
              </group>
              <shared>sample string 1</shared>
            </memberGroupSharedItem>
          </sharedGroups>
          <sharedUsers>
            <userSharedItem>
              <errorDetails>
                <errorCode>SUCCESS</errorCode>
                <message></message>
              </errorDetails>
              <shared>sample string 1</shared>
              <user />
            </userSharedItem>
          </sharedUsers>
          <templateId>sample string 1</templateId>
          <templateName>sample string 2</templateName>
        </templateSharedItem>
      </templates>
      <user>
        <activationAccessCode>sample string 9</activationAccessCode>
        <email>sample string 3</email>
        <errorDetails>
          <errorCode>sample string 1</errorCode>
          <message>sample string 2</message>
        </errorDetails>
        <loginStatus>sample string 7</loginStatus>
        <sendActivationEmail>sample string 8</sendActivationEmail>
        <uri>sample string 6</uri>
        <userId>sample string 2</userId>
        <userName>sample string 1</userName>
        <userStatus>sample string 5</userStatus>
        <userType>sample string 4</userType>
      </user>
    </memberSharedItems>
  </sharedAccess>
  <startPosition>sample string 3</startPosition>
  <totalSetSize>sample string 2</totalSetSize>
</accountSharedAccess> 
}} />