How to clone an account

This topic demonstrates how to create a new Docusign eSignature account in your organization by cloning an existing account.

Note: Cloning copies some features of the source account to the target account, but not others; see Clone eSignature accounts for details.

Required data

Running the code in this how-to requires this data:

Step 1. Obtain your OAuth token

To make the API call(s) shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different OAuth grant types: Authorization Code Grant, Implicit Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Docusign Admin OAuth access tokens are the same ones used for our eSignature REST API, although you must request one or more Docusign Admin scopes to call the Docusign Admin API. The endpoint calls made in this how-to require that you request the following Docusign Admin-specific scopes when obtaining your access token: asset_group_account_read, asset_group_account_clone_write, and asset_group_account_clone_read.

See Docusign Admin Authentication for the full list of Docusign Admin scopes.

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}"
    '--header' "Accept: application/json"
    '--header' "Content-Type: application/json")

Step 3. Get the list of eligible accounts

First, determine the accounts in your organization that are eligible to be cloned. To get a list of accounts in an organization that are in compliance, call the AccountCloning:getAssetGroupAccounts endpoint. Be sure to substitute your organization ID for {ORGANIZATION_ID}.

Status=$(curl --request GET ${base_path}/v1/organizations/${ORGANIZATION_ID}/assetGroups/accounts?compliant=true \
"${Headers[@]}" \
--output ${response})

Step 4. Construct the request body

Next, construct the request body for the API call that will clone the account. Replace {SOURCE_ACCOUNT_ID} with the ID of one of the compliant accounts that was identified in the previous step. This is the ID of the account that will be cloned. Inside the targetAccount object, replace {ACCOUNT_NAME}, {FIRST_NAME}, {LAST_NAME}, and {EMAIL} with the name and email address of the administrator for the new account. This administrator should already exist as an admin user in your organization.

The countryCode parameter is used to determine the data residency for the new account. In the developer environment there is only one region available, and the value should be set to "US". In the production environment this value can be set to the two-character ISO 3166 country code for the country of the target account.

# The country code value is set to "US" for the developer environment
# In production, set the value to the code for the country of the target account
printf \
'{
    "sourceAccount": {
        "id": "'${SOURCE_ACCOUNT_ID}'"
    },
    "targetAccount": {
        "name": "'${ACCOUNT_NAME}'",
        "admin": {
            "firstName": "'${FIRST_NAME}'",
            "lastName": "'${LAST_NAME}'",
            "email": "'${EMAIL}'"
        },
        "countryCode": "US"
    }
}
' >>$request_data

Step 5. Call the Docusign Admin API to clone the account

Now that you have constructed your API headers and request body, make a POST request to the AccountCloning:cloneAssetGroupAccount method and include the request body to clone the account. Here’s how you make the call, but make sure to substitute your organization ID for {ORGANIZATION_ID}. This will clone the source account into a new Docusign eSignature account.

Status=$(curl --request POST ${base_path}/v1/organizations/${ORGANIZATION_ID}/assetGroups/accountClone \
"${Headers[@]}" \
--data-binary @${request_data} \
--output ${response})

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

Depending on the organization settings, the admin of the new account will receive an email with a link to activate the new account, or the account will automatically be activated. If the account does need to be activated, the status in the JSON response will be “Pending” until the account is activated.

{
  "sourceAccount": {
    "id": "ed3efc40-xxxx-xxxx-xxxx-17b8f1caab2b"
  },
  "targetAccount": {
    "id": "00000000-xxxx-xxxx-xxxx-000000000000",
    "name": "Target Account",
    "region": "NA",
    "site": "Demo",
    "admin": {
      "email": "example@example.com",
      "firstName": "Donna",
      "lastName": "Developer"
    }
  },
  "assetGroupWorkId": "56cf1cf2-xxxx-xxxx-xxxx-00758573acdf",
  "assetGroupId": "ef233c93-xxxx-xxxx-xxxx-5e53e7a3c56b",
  "assetGroupWorkType": "AccountAssetClone",
  "status": "Pending",
  "attempts": 0,
  "createdDate": "2023-08-14T20:49:45.2754641Z",
  "message": "Awaiting Asset Group Work Job"
}

Next steps

• Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
• Learn more about cloning eSignature accounts.
• Learn How to create a new active eSignature user.
• See how to Go-Live with a completed app and find the base path for API calls in the production environment.