Accounts: listSharedAccess

Retrieves shared item status for one or more users and types of items.

Users with account administration privileges can retrieve shared access information for all account users. Users without account administrator privileges can only retrieve shared access information for themselves, and the returned information is limited to retrieving the status of the members of the account that are sharing their folders to the user. This is equivalent to setting the shared parameter to shared_from.

Request

HTTP request

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

Parameters

Parameter Name	Value	Description
Path Parameters
accountId	string	The external account number (int) or account ID GUID.
Optional Query Parameters
count	string	Specifies the maximum number of results included in the response. If no value is specified, this defaults to 1000.
envelopes_not_shared_user_status	string	This query parameter works in conjunction with `user_ids`. When you specify one of the following user statuses, the query limits the results to only users that match the specified status: `ActivationRequired`: Membership Activation required `ActivationSent`: Membership activation sent to user `Active`: User Membership is active `Closed`: User Membership is closed `Disabled`: User Membership is disabled
folder_ids	string	A comma-separated list of folder IDs for which to return shared item information. If `item_type` is set to `folders`, at least one folder ID is required.
item_type	string	Specifies the type of shared item being requested. The possible values are: `envelopes`: Get information about envelope sharing between users. `templates`: Get information about template sharing among users and groups. `folders`: Get information about folder sharing among users and groups.
search_text	string	Filter user names based on the specified string. The wild-card '*' (asterisk) can be used in the string.
shared	string	A comma-separated list of sharing filters that specifies which users appear in the response. `not_shared`: The response lists users who do not share items of `item_type` with the current user. `shared_to`: The response lists users in `user_list` who are sharing items to current user. `shared_from`: The response lists users in `user_list` who are sharing items from the current user. `shared_to_and_from`: The response lists users in `user_list` who are sharing items to and from the current user. If the current user does not have administrative privileges, only the `shared_to` option is valid.
start_position	string	If the number of responses is greater than `count`, this specifies the number of responses to skip. Typically this value is a multiple of `count`. The default is 0.
user_ids	string	A comma-separated list of user IDs for whom the shared item information is being requested.

Responses

Code	Description	Reference
200	Successful response.	accountSharedAccess
400	Error encountered.	errorDetails

Code

Description

Reference

200

Successful response.

accountSharedAccess

400

Error encountered.

errorDetails

SDK Method

Accounts::listSharedAccess

Definitions

accountSharedAccess

Contains shared access information.
`accountId`	string	The account ID associated with the envelope.
`endPosition`	string	The last position in the result set.
`errorDetails`	errorDetails	A complex type containing an errorCode and message identifying the error that occurred.
`nextUri`	string	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`	string	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`	string	The number of results returned in this response.
`sharedAccess`	[memberSharedItems]	A list of shared access information of envelope and templates for the users specified in the request.
`startPosition`	string	Starting position of the current result set.
`totalSetSize`	string	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.

errorDetails

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

errorCode

string

A code associated with the error condition.

message

string

A brief message describing the error condition.

folderSharedItem


`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`folderId`	string	Unique identifier for the folder.
`name`	string	The folder name.
`owner`	userInfo	Information about the user who owns the folder.
`parentFolderId`	string	Unique identifier for the parent folder.
`parentFolderUri`	string	URI for the parent folder.
`shared`	string	How the folder is shared. One of: `not_shared` `shared_to` `shared_from` `shared_to_and_from`
`sharedGroups`	[memberGroupSharedItem]	List of groups that share the folder.
`sharedUsers`	[userSharedItem]	List of users that share the folder.
`uri`	string	URI containing the user ID.
`user`	userInfo	Information about the user associated with the folder.

group

Information about groups.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`groupId`	string	The DocuSign group ID for the group.
`groupName`	string	The name of the group.
`groupType`	string	The group type. Potential values for POST and PUT requests include: `adminstrators` `everyone` `customGroup`
`permissionProfileId`	string	The ID of the permission profile associated with the group. Potential 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.
`usersCount`	string	The total number of users in the group.

memberGroupSharedItem

Information about items shared among groups.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`group`	group	The group sharing the item.
`shared`	string	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.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`folders`	[folderSharedItem]	List of information about shared folders.
`templates`	[templateSharedItem]	List of information about shared templates.
`user`	userInfo	Information about the user requesting sharing information.

sharedItem

Information about the shared item.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`shared`	string	How the item is shared. One of: `not_shared` `shared_to` `shared_from` `shared_to_and_from`
`user`	userInfo	Information about the user who owns the shared item.

templateSharedItem

Information about shared templates.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`owner`	userInfo	Information about the user who owns the template.
`password`	string	The user's encrypted password hash.
`shared`	string	How the template is shared. One of: `not_shared` `shared_to` `shared_from` `shared_to_and_from`
`sharedGroups`	[memberGroupSharedItem]	List of groups that share the template.
`sharedUsers`	[userSharedItem]	List of users that share the template.
`templateId`	string	The unique identifier of the template. If this is not provided, DocuSign will generate a value.
`templateName`	string	The name of the shared template.

userInfo


`accountId`	string	The external account number (int) or account ID GUID.
`accountName`	string	The name of the account associated with the current workspace user.
`activationAccessCode`	string	Access code provided to the user to activate the account.
`email`	string	Filters returned user records by the specified email address.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`loginStatus`	string	Boolean value that indicates whether the user is currently logged in or not.
`membershipId`	string	The user's membership ID.
`sendActivationEmail`	string	When set to true, specifies that an activation email be sent to the user.
`uri`	string	URI containing the user ID.
`userId`	string	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 Administrator on the account, this can be another user the Admin user is accessing. Note: For Envelopes:listStatusChanges (`GET /v2.1/accounts/{accountId}/envelopes`), the `user_id` query parameter is not implemented and should not be used.
`userName`	string	The name of the user.
`userStatus`	string	Status of the user's account. One of: `ActivationRequired` `ActivationSent` `Active` `Closed` `Disabled`
`userType`	string	The type of user, for example `CompanyUser`.

userSharedItem

Information about a shared item.
`errorDetails`	errorDetails	Object that describes errors that occur. Only valid for responses; ignored in requests.
`shared`	string	How the item is shared. One of: `not_shared` `shared_to` `shared_from` `shared_to_and_from`
`user`	userInfo	The user whose sharing information is being requested.

Examples

Generic JSON Response

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 Response

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>

}} />