Scaling with Docusign: The ISV՚s guide to account cloning

As an ISV partner, efficiency isnʼt just a goal; itʼs essential for scaling your operations. Manually provisioning new eSignature accounts is time-consuming and prone to error. The Docusign account cloning feature is a powerful tool designed to solve this exact problem. It allows you to create new, perfectly configured accounts by simply copying the settings programmatically from an existing account (called a source account).

Whether youʼre setting up consistent configurations for different regions, departments, or integration environments, this guide will walk you through the entire process using the Docusign Admin API.

How account cloning differs from account creation

When you create a new account in your organization, you supply all the required account settings. Account cloning, on the other hand, creates a new target account by duplicating the complete configuration of a source account within your Docusign organization. This includes settings, branding, user permissions, and more.

Think of it as a "copy-paste" for entire account setups. This process saves you significant time and effort, guaranteeing that every new account is provisioned correctly and consistently without manual intervention.

Important limitations: What isnʼt copied

While account cloning is fantastic for replicating core settings, itʼs crucial to understand that it does not copy account-specific data or certain user-related configurations. The goal is to provide a clean, ready-to-configure account.

The following items are not copied from the source account to the target account:

• Users (except for the new account administrator you define during the cloning request)

• Groups

• Signing groups

• Custom permission profiles

• Integrations listed on the Apps and Keys page (including integration keys)

• Templates

• Elastic templates

• Brands

• Connect configurations

These items are typically unique to an accountʼs specific users and workflows, and you will need to set them up separately after the new target account has been created.

Step 1. Enable the cloning feature

Account cloning is an advanced feature that must be enabled for your developer (demo) or production account before you can use it.

1. Locate your organization ID: Log in to your Docusign developer account, navigate to Settings, and find your Organization ID under the Organization section of the Account Profile page.

2. Request activation: Send an email to the Docusign ISV team at isvbuild@docusign.com. Include your organization ID in the email and request that account cloning be enabled.

Step 2. Make the cloning API call

Once the feature is active, you can use the Docusign Admin API to clone an account. Hereʼs what youʼll need:

Obtain an access token

Your authentication method must request the correct permissions to perform cloning operations. Ensure that your scope includes the following values:

signature impersonation asset_group_account_read asset_group_account_clone_write asset_group_account_clone_read

Use the correct base URI

All account cloning API requests must be directed to the correct environment endpoint.

• Developer environment: https://api-d.docusign.net

• Production: https://api.docusign.net

Gather required IDs

Youʼll need three specific IDs for your API request:

• Organization ID (orgId): Found on the Admin > Account > Account Profile page.

• Asset group ID (assetGroupId): Obtain this by calling the getAssetGroupAccounts endpoint. This ID represents a grouping of accounts within your organization.

  • Sample call on developer environment: GET https://api-d.docusign.net/Management/v2/organizations/{orgId}/assetGroups/accounts?compliant=true

• Source account ID: This is the API account ID of the account you wish to clone. You can find it on the Admin > Integrations > Apps and Keys page of that source account.

Set the data center location

You must specify the data residency for the new account using the countryCode property.

• In the developer environment, this value must be set to US.

• In the production environment, this can be set to the two-character ISO 3166 country code for the target accountʼs country (for example, CA).

Step 3. Put it all together (sample request)

Here is an example of the JSON payload to initiate the cloning process.

• Endpoint: POST https://api-d.docusign.net/management/v2/organizations/{orgId}/assetGroups/{assetGroupId}/account_clones

• Payload: JSON

{
  "sourceAccount": {
    "id": "f36974ab-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "targetAccount": {
    "name": "New Cloned Account - Project Phoenix",
    "admin": {
      "firstName": "Abhay",
      "lastName": "Nelaturu",
      "email": "abhay.nelaturu@example.com"
    },
    "countryCode": "US"
  }
}

Step 4. Check the cloning status

Account cloning is an asynchronous process. After you make the POST request, the system begins creating the account in the background, which typically takes two to three minutes.

Your initial POST request will return an assetGroupWorkId. You must use this ID to poll for the status of the cloning job.

• Status check endpoint: GET https://api-d.docusign.net/Management/v2/organizations/{organizationId}/assetGroups/{assetGroupId}/accountClones/{assetGroupWorkId}

Check the status parameter in the response. A status of completed indicates the new account is ready.

Note: The system processes only one cloning request at a time per asset group. If you need to perform bulk cloning, design your workflow to queue requests and make subsequent calls only after the previous one has completed.

The Pending tab on the Organization Accounts page also displays the cloning operation status.

Troubleshooting common cloning errors

If you run into issues, API logs are the best way to diagnose the problem. You can enable and download logs from your developer account. Sharing these logs with the ISV build team will help resolve problems quickly.

Here are a few common errors you might encounter:

Receiving an HTML page instead of a JSON response

• Symptom: The API response is a large block of HTML code showing a 404 - File or directory not found error.

• Cause: This almost always means the base URI or the endpoint path in your API call is incorrect.

• Resolution: Double-check that your base URI is correct for the environment and that the endpoint path is correct. See Docusign API endpoint base paths for more information.

Request status is pending_error

• Symptom: The cloning job status shows pending_error.

• Cause: This can happen if there was an issue during the initial validation of the request. Often, itʼs due to incorrect parameters like a malformed ID or an invalid region.

• Resolution: Wait a few minutes to see if the system resolves it. If not, carefully verify all the IDs (orgId, assetGroupId, sourceAccountId) and parameters (countryCode) in your original request payload.

Request status is processing_error

• Symptom: The cloning job status shows processing_error.

• Cause: This indicates an issue occurred on the server while cloning was in progress.

• Resolution: Donʼt panic! The system will often automatically re-attempt the cloning process after a few minutes. Continue to poll the status endpoint. If the error persists after several attempts, review your API logs and contact the ISV support team for assistance.

Conclusion

By leveraging the Admin API account cloning feature, you can dramatically accelerate your onboarding process, ensure consistency across your customer base, and free up valuable developer time. Happy cloning!

Additional resources

• Get an overview of the account cloning feature.

• Read a step-by-step walkthrough of cloning an account programmatically.

• Review account cloning code examples in Bash, C#, Java, Node.js, PHP, PowerShell, Python, and Ruby.

• Get details about API endpoints related to account cloning.