GetSharedAccess | Docusign

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

Schema

Name	Schema Type	Description
AccountId	String	Account Id.
SharedAccessFilters	Array of SharedAccessFilter	An array of SharedAccessFilter that defines the requested user and shared item information.

SharedAccessFilter Schema

Name	Schema Type	Description
UserIds	Array of UserIds	An array of User Ids for whom the shared item information is being requested.
ItemType	ItemType	Specifies the type of shared item being requested. The accepted values are: Envelopes: returns information about envelope sharing between users.
SearchText	String	Optional field. This can be used to filter user names in the response. The wild-card ‘%’ can be used around the string. If no value is specified, then there is no filtering of user names.
Shared	Shared	Optional field. Specifies which users should be included in the response by setting the sharing status for the requested user (by UserId) and item (by ItemType). If no value is specified and the requester has account administrator privileges, then the request returns item sharing status for all active account users. If no value is specified and the requestor does not have account administrator privileges, the SharedTo value is used. Requestors that do not have account administrator privileges can only use the SharedTo, any other setting will result in an error. The accepted values are: - NotShared: Returns account users that the specified item type is not being shared with and that are not sharing the specified item type with the user. User x (Share) x Account user - SharedTo: Returns account users that the specified item type is not being shared with and who are sharing the specified item type with the user (only shared to the user). User < (Share) Account user - SharedFrom: Returns account users that the specified item type is being shared with and who are not sharing the specified item type with the user (only shared from the user). User (Share) > Account user - SharedToAndFrom: Returns account users that the specified item type is being shared with and who are sharing the specified item type with the user. User < (Share) > Account user
StartAtIndex	nonNegativeInteger	Optional Field. If a shared access response set exceeds Count, this element can be used to specify that the method should return users starting at the specified index. The first index is 0, and should be used in the first GetSharedAccess call. Typically this number is a multiple of Count. If no value is specified, this defaults to be 0.
Count	nonNegativeInteger	Optional Field. Specifies how many sharedItems results are included in the response. If no value is specified, this defaults to 1000.

Sample Request XML

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<env : Body>
    <GetSharedAccess xmlns="http://www.docusign.net/API/3.0">
      <AccountId>b9ddeca5-xxxx-xxxx-xxxx-11e8a595e740</AccountId>
      <SharedAccessFilter>
        <UserIds>
          <UserId>4af36b6c-xxxx-xxxx-xxxx-4212e419a78c</UserId>
          <UserId>dcde4bbd-xxxx-xxxx-xxxx-171bdcb6974d</UserId>
          <UserId>d1375465-xxxx-xxxx-xxxx-4c0dad592dfa</UserId>
        </UserIds>
        <ItemType>Envelopes</ItemType>
        <SearchText>%John%</SearchText>
        <Shared>SharedTo</Shared>
        <StartAtIndex>0</StartAtIndex>
        <Count>4</Count>
      </SharedAccessFilter>
    </GetSharedAccess>
  </env:Body>
</env:Envelope>

The response provides information about the result set, an array of the shared items, and either a success or failure. If the call fails an error code is provided.

A description of the information in the response is given below.

| Name | Schema Type | Description | | --- | --- | --- | | AccountId | String | Account Id. | | ResultSetSize | nonNegativeInteger | The number of results returned in this response. | | TotalSetSize | nonNegativeInteger | The total number of results from the call. This will always be greater than or equal to ResultSetSize. | | StartAtIndex | nonNegativeInteger | The index of the first element in the response set. | | EndAtIndex | nonNegativeInteger | The index of the last element in the response set. | | SharedItems | Array of SharedItems objects | The shared access information for the users specified in the request. See description below for more information. |

Description of SharedItems objects

| Name | Schema Type | Description | | --- | --- | --- | | User | User object | The information for the user associated with the shared item information in this object. | | SharedItem | Array of SharedItem objects | Shared item information for the user. See description below for more information. | | ErrorDetails | ErrorDetails object | Error information related to this user. |

Description of SharedItem objects

Name	Schema Type	Description
User	User object	The information for the account user associated with this shared status. See description below for more information.
Shared	Shared status	Specifies the current sharing status between the requested user and other account users for the specified item type. - NotShared: The specified item type is not being shared with this account user and the account user not sharing the specified item type with the user. User x (Share) x Account user - SharedTo: The specified item type is not being shared with the account user and the account user is sharing the specified item type with the user (only shared to the user). User < (Share) Account user - SharedFrom: The specified item type is being shared with the account user and the account user is not sharing the specified item type with the user (only shared from the user). User (Share) > Account user - SharedToAndFrom: The specified item type is being shared with the account user and account user is sharing the specified item type with the user. User < (Share) > Account user
ItemType	ItemType	The type of the shared item. Currently the only ItemType supported is Envelopes.

Description of User objects

| Name | Schema Type | Description | | --- | --- | --- | | UserId | UserId | User Id of the account user. | | Email | String | Email for the account user. | | UserName | String | User name for the account user. |

Sample Response XML

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<env: Body>
    <GetSharedAccessResponse xmlns=" http://www.docusign.net/API/3.0">
      <GetSharedAccessResult>
        <AccountId>b9ddeca5-2eb0-448b-b304-11e8a595e740</AccountId>
        <ResultSetSize>4</ResultSetSize>
        <TotalSetSize>50</TotalSetSize>
        <StartAtIndex>0</StartAtIndex>
        <EndAtIndex>3</EndAtIndex>
        <SharedItems>
          <User>
            <UserId>4af36b6c-8475-491f-8be9-4212e419a78c</UserId>
            <Email>some.name@docusign.com</Email>
            <UserName>Some Name</UserName>
          </User>
          <SharedItem>
            <User>
              <UserId>1272b5d0-f7d1-4295-bcb0-ce8ccafdffd4</UserId>
              <Email>elton.john@docusign.co</Email>
              <UserName>Elton John</UserName>
            </User>
            <Shared>NotShared</Shared>
            <ItemType>Envelopes</ItemType>
          </SharedItem>
          <SharedItem>
            <User>
              <UserId>1f2289df-01d7-4bd7-b581-bb70362ea662</UserId>
              <Email>john.doe@docusign.com</Email>
              <UserName>John Doe</UserName>
            </User>
            <Shared>NotShared</Shared>
            <ItemType>Envelopes</ItemType>
          </SharedItem>
        </SharedItems>
        <SharedItems>
          <User>
            <UserId>dcde4bbd-d8f1-442b-a1be-171bdcb6974d</Userid>
            <Email>another.name@docusign.com</Email>
            <UserName>Another Name</UserName>
          </User>
          <SharedItem>
            <User>
              <UserId>1272b5d0-f7d1-4295-bcb0-ce8ccafdffd4</UserId>
              <Email>calamity.jane@docusign.com</Email>
              <UserName>Calamity Jane</UserName>
            </User>
            <Shared>SharedTo</Shared>
            <ItemType>Envelopes</ItemType>
          </SharedItem>
          <SharedItem>
            <User>
              <UserId>1f2289df-01d7-4bd7-b581-bb70362ea662</UserId>
              <Email>jane.doe@docusign.com</Email>
              <UserName>Jane Doe</UserName>
            </User>
            <Shared>SharedToAndFrom</Shared>
            <ItemType>Envelopes</ItemType>
          </SharedItem>
        </SharedItems>
        <Error>
          <ErrorCode>string</ErrorCode>
          <Description>string</Description>
        </Error>
      </GetSharedAccessResult>
    </GetSharedAccessResponse>
  </soap:Body>
</soap:Envelope>