Clone eSignature accounts

Account cloning enables you to create an eSignature account in your organization by copying features of an existing account, referred to as a source account, to a new account, referred to as a target account. This can be useful for quickly provisioning accounts that your organization uses to differentiate business operations based on region, department, integration features, or other requirements. See Considerations Before Creating New Accounts for information about when it’s appropriate to create an account rather than using an existing account.

You can clone accounts via API requests or by using Docusign Admin.

Features that are copied when cloning an account

When you clone an account, these features of the target account will be identical to those of the source account:

• The eSignature account plan: This defines general account features.
• Modules: These include add-ons that provide enhanced functionality, such as SMS and WhatsApp delivery and CFR Part 11.
• Settings: These determine account behavior in areas such as envelope sending, signing, and security.

These items are not copied to the target account:

• Users
• Groups
• Signing groups
• Permission profiles
• Integrations listed on the Apps and Keys page
• Templates
• Elastic templates
• Brands
• Connect configurations

Account cloning behaviors and restrictions

These sections describe account cloning behaviors and restrictions:

• Cloning occurs within an organization
• Source accounts must be compliant
• All source account settings are copied
• Up to five processes can be active per source account
• Do not modify source account while cloning is in progress
• Target account administrator must be an organization admin
• Target account properties determine data residency

Cloning occurs within an organization

Account cloning occurs within the context of an organization. Because of this, cloning is subject to the following restrictions:

• The user who initiates an account cloning API request must be an organization administrator of the organization whose ID is specified in the request.
• The source account must be under the organization whose ID is specified in the API request. You cannot clone accounts that are not associated with an organization.
• By default, the target account will be in the same organization as the source account. If you do not want the target account to be in that organization, after the cloning process has finished, you can unlink the account and link it to a different organization.

Source accounts must be compliant

In order for a source account to be cloned, it must meet Docusign compliance criteria. Docusign evaluates account compliance by checking the asset group to which the account belongs. An asset group consists of all the plan items covered by the account subscription with Docusign. If an account has plan items enabled that are not included in its asset group, the account is considered noncompliant, and it cannot be cloned.

Before attempting to clone a source account, you can check whether it’s compliant by making an AccountCloning:getAssetGroupAccounts request. It returns a list of your organization’s accounts, with a compliant property that indicates whether each account is compliant.

If a source account is not compliant, you have two options:

• Clone a different account. Every organization has at least one compliant account.
• Contact Docusign Support to explore options for bringing the account into compliance.

All source account settings are copied

The cloning process copies all source account settings to the target account. If you want to change target account settings, you can do so after the target account has been activated.

Up to five processes can be active per source account

You can run up to five cloning processes per source account at any given time, allowing you to create up to five target accounts concurrently.

To create more than one target account from the same source account, launch a separate AccountCloning:cloneAssetGroupAccount request for each target account.

For details on tracking progress and status, see the Cloning request processing documentation.

Do not modify source account while cloning is in progress

To avoid unexpected results for a target account, Docusign recommends that you do not modify settings for a source account while a clone of that account is in progress. Cloning request processing has information about how you can determine when a cloning process has finished.

Target account administrator must be an organization admin

An account cloning API request includes a targetAccount.admin object that defines an account administrator for the target account. The administrator specified in the AccountCloning:cloneAssetGroupAccount request must already exist as a user in your organization with organization admin permissions. If you want to define additional administrators for the target account, you can do so after the account has been activated.

Target account properties determine data residency

An account cloning API request includes properties that define data residency for the target account. You have the option of specifying a country code (targetAccount.countryCode property) or a region (targetAccount.region property) in the AccountCloning:cloneAssetGroupAccount request. Docusign recommends supplying a country code, and the target account will be mapped automatically to a data center. Valid country code values are the two-letter ISO 3166 country codes.

If the source account and the target account have the same country code or region, the target account will be assigned the same Docusign data center as the source account. Otherwise, the target account will be assigned to the default data center for the country or region specified in the request to clone the account.

API endpoints and required scopes for account cloning

The AccountCloning Resource includes four endpoints related to the cloning process. This section describes each endpoint and lists the scope that you must supply during authentication in order to use the endpoint.

All account cloning requests require an organization ID. You can obtain your organization ID via a request to the Organization:getOrganizations endpoint or by copying it from the Organization section of the Account Profile page.

Cloning request processing

If an AccountCloning:cloneAssetGroupAccount request succeeds, the response looks like this:

{
  "sourceAccount": {
    "id": "dac17ad7-xxxx-xxxx-xxxx-873f3b4cb7e2"
  },
  "targetAccount": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "TestClone",
    "region": "NA",
    "site": "Demo",
    "admin": {
      "email": "test@email.com",
      "firstName": "TestFirst",
      "lastName": "TestLast"
    }
  },
  "assetGroupWorkId": "c9da77ee-xxxx-xxxx-xxxx-347704226e15",
  "assetGroupId": "ef233c93-xxxx-xxxx-xxxx-5e53e7a3c56b",
  "assetGroupWorkType": "AccountAssetClone",
  "status": "Pending",
  "attempts": 0,
  "createdDate": "2023-08-09T13:46:20.268974Z",
  "message": "Awaiting Asset Group Work Job"
}

The Pending status indicates that the cloning process will begin shortly. The response contains a placeholder value for targetAccount.id, because the account ID won’t be available until the cloning process has finished successfully, which can take up to 10 minutes. Keep in mind that after a success response to an AccountCloning:cloneAssetGroupAccount request, it’s still possible for the cloning process to fail.

You can monitor the cloning process status and retrieve the target account ID by using the AccountCloning:getAssetGroupAccountClone call. You identify the cloning process by populating assetGroupWorkId in this request with the value returned in the response to the AccountCloning:cloneAssetGroupAccount request. You can also use the AccountCloning:getAssetGroupAccountClonesByOrgId call, which returns information about all cloning processes for an organization. A Processing status indicates that cloning is in progress. Upon successful completion, the status will be Completed, and the targetAccount.id property will contain the ID of the new account.

If a cloning process fails, the AccountCloning:getAssetGroupAccountClone and AccountCloning:getAssetGroupAccountClonesByOrgId requests return a PendingError status, and the cloneProcessingFailureDetails property provides an error code and message. Docusign will retry a failed cloning process 10 times. The attempts property in the responses to the two GET requests tracks the number of retries attempted. If a retry succeeds, the GET requests return a Completed status. If none of the 10 retries succeeds, the GET requests return a PermanentFailure status, and the cloneProcessingFailureDetails object contains the error code and message for the last retry.

Target account activation

Upon successful completion of a cloning process, account activation for the target account’s administrator occurs as follows, depending on the organization’s Signup Settings:

• If the organization is configured to activate memberships automatically, no action is needed from the target account administrator to activate their membership in the target account.
• If automatic activation is not enabled, the target account’s administrator will receive an email with the subject line Account Activation. The administrator must click the Activate link in the email to complete the process of assuming the administrator role for the target account.

After automatic or manual account activation, the target account administrator will see the account in the list displayed when they switch between accounts in the eSignature web application.

Close unneeded target accounts

If you have accounts in your organization created via the cloning process that you no longer need, you can file a Support ticket to request that they be closed. See Close an account for details.

Troubleshoot account cloning errors

This section describes issues that can cause an account cloning process to fail. The errors may appear in the response to any of these requests:

• AccountCloning:cloneAssetGroupAccount
• AccountCloning:getAssetGroupAccountClone
• AccountCloning:getAssetGroupAccountClonesByOrgId

Source account errors

The request to clone an account includes a sourceAccount.id property, which identifies the account to clone. These errors can occur as a result of issues with the source account:

Target account errors

The request to clone an account includes a targetAccount object that defines properties associated with the target account. These errors can occur as a result of issues with this definition:

Next steps

For more information about account cloning, see:

• How to clone an account
• AccountCloning Resource in the API reference
• Clone an Existing Account in the Docusign Admin Guide