Blog
Home/

Docusign Admin API: closing user membership vs. deleting user data

Ahmed Shorim
Ahmed ShorimSr. Developer Support Advisory Engineer
    • What is closing user membership?
    • What is deleting user data?
    • Use cases
        • Additional resources

        Table of contents

        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:

        1. In Docusign eSignature, select Settings, then select Users from the left nav.

        2. Select the Status filter:

        3. Check the Closed checkbox, then select Apply:

        4. 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:

        1. 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.

        2. 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 statusparameter:

        • success

        • pending

        • failure

        • already_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:

        • success

        • pending

        • failure

        • already_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.

        Additional resources

        Ahmed Shorim
        Ahmed ShorimSr. Developer Support Advisory Engineer

        Ahmed Shorim has been with Docusign since 2021 as a Senior Developer Support Advisory Engineer. His work is focused on advising developers on how to integrate with Docusign APIs and SDKs by consulting on best practices and providing code examples. Experienced in developing web, mobile, and desktop applications along with building automation flows, he can be reached at LinkedIn.

        More posts from this author

        Related posts

        • Code Examples

          Fast-Track Your Extension Apps with Reference Implementations

          Karissa Jacobsen
          Karissa Jacobsen
        • Paige Rossi
          Paige Rossi
        • Developer Spotlight is Coming to Docusign Community!

          Matthew Lusher
          Matthew Lusher

        Fast-Track Your Extension Apps with Reference Implementations

        Karissa Jacobsen
        Karissa Jacobsen
        Paige Rossi
        Paige Rossi

        Developer Spotlight is Coming to Docusign Community!

        Matthew Lusher
        Matthew Lusher

        Discover what's new with Docusign IAM or start with eSignature for free

        Explore Docusign IAMTry eSignature for Free
        Person smiling while presenting