DocuSign Admin API: closing user membership vs. deleting user data
There are two DocuSign Admin API endpoints, DataDeletion:redactIndividualMembershipData and DataDeletion:redactIndividualUserData, that enable administrators to delete an eSignature user’s personally identifiable information (PII), while there is one DocuSign Admin API endpoint, eSignUserManagement:closeMemberships, that enables administrators to close a user’s membership in the administrator’s DocuSign account. Let’s compare these endpoints and identify appropriate use cases for deleting user data.
What is closing user membership?
Using the eSignUserManagement:closeMemberships API endpoint results in deactivating the user’s membership in your DocuSign account, marking the user’s status as “closed”; but their data remains in your account. This blocks the user’s access to that account, but allows you to activate the same user again with the same user data later on if needed.
To view the closed users on your account:
- In DocuSign eSignature, select Settings, then select Users from the left nav.
- Select the Status filter:
- Check the Closed checkbox, then select Apply:
- The users list will refresh and you will be able to see the full list of users, including closed ones.
This means that even if you close the user’s membership, their data will remain and you can choose to reactivate them.
What is deleting user data?
Let's imagine that one of your employees is leaving the company and you did close their user membership, but you need to delete their personal identifiable information (PII) completely from your DocuSign account (say, for privacy regulations, such as GDPR). This is where the deletion API endpoints come into play.
You have two ways of deleting user membership data:
- Use the DataDeletion:redactIndividualMembershipData, which enables you to delete the data for a single account membership for a specified user. You must be an administrator (or delegated administrator) of the specified account.
- Use the DataDeletion:redactIndividualUserData which enables you to delete data for one or more of a user's account memberships. You must be an organization administrator (or delegated administrator) with permission to manage the specified accounts or the user's email domain.
For the data deletion to happen successfully, the user’s membership must have been closed for at least 24 hours previously. This acts as a safeguard to avoid deleting user data accidentally. If you try the deletion within 24 hours of closing the user’s membership (or trying to delete an active user), you will get the following error:
"error": "membership_close_not_allowed"
To fully delete a user’s profile data, you must delete all their membership data across accounts. For example, if a user is a member of three accounts, be sure to delete their membership data in all three (which will then remove all profile data associated with that user).
Use cases
Use case 1: You are an administrator of a specific account and would like to delete the data of a user in your account.
If you do not already have the user ID of the user you would like to delete, then you can use the Users:getUsers API to search for the user using their email address.
Method: POST
URL: https://api-d.docusign.net/management/v2/data_redaction/accounts/<API_ACCOUNT_ID>/user
Payload:
{
"user_id": "<USER_ID_TO_DELETE>"
}
Response:
{
"user_id": "<USER_ID_DELETED>",
"status": "success",
"membership_results": [
{
"account_id": "<API_ACCOUNT_ID>",
"status": "success"
}
]
}
Possible values for the status parameter:
successpendingfailurealready_redacted
Use case 2: You are an organization administrator and would like to delete the data of a user in multiple accounts.
If you do not already have the user ID of the user you would like to delete, then you can use the Users:getUsers API to search for the user using their email address.
If you do not already have the account IDs for the DocuSign accounts to which the user belongs, then you can use the eSignUserManagement:getUserProfiles to search for the account IDs using the user’s email address.
Method: POST
URL: https://api-d.docusign.net/management/v2/data_redaction/organizations/<ORGANIZATION_ID>/user
Payload:
{
"user_id": "<USER_ID_DELETED>",
"memberships": [
{
"account_id": "<API_ACCOUNT_ID_1>"
},
{
"account_id": "<API_ACCOUNT_ID_2>"
}
]
}
The memberships parameter is an array: you list in it the account IDs from which you want to delete the user’s data.
Response:
{
"user_id": "<USER_ID_DELETED>",
"status": "success",
"membership_results": [
{
"account_id": "<API_ACCOUNT_ID_1>",
"status": "success"
},
{
"account_id": "<API_ACCOUNT_ID_2>",
"status": "success"
}
]
}
The top status parameter is the overall status of the deletion request, while the ones inside the membership-results array are individual status values for each deletion.
Possible values for the status parameter:
successpendingfailurealready_redacted
Use case 3: Bulk user deletion
If several users need PII removed at once, the recommendation would be to loop through the users that need to be deleted and call the appropriate API from one of the two previous use cases.
