Create new eSignature accounts | Docusign

This feature is only available in the production environment. To request to enable account creation and account cloning in your developer account, contact Docusign Support and include your demo organization ID, which you can obtain from the Organization section of the Account Profile page.

New eSignature accounts can be created in your organization through the Docusign Admin API or through Docusign Admin. You must be an organization administrator to perform these actions. See Considerations Before Creating New Accounts for information about when it’s appropriate to create an account rather than using an existing account.

Defining the new account

When you create a new account with the API, you specify the following features of the account in your API request body.

Subscription ID: The ID of the subscription under which the new account will be created.
Plan ID: The ID of the eSignature account plan that defines general account features.
Modules: Any add-ons that provide enhanced functionality, such as SMS and WhatsApp delivery and CFR Part 11.
Account name: The name of the new account.
Country code: This determines the data residency of the new account. In the production environment this value can be set to the two-character ISO 3166 country code for the country of the target account.
Admin: Information about the new account admin including name and email address.

The request body should look like this:

{
    "subscriptionDetails": {
        "id": "'${SUBSCRIPTION_ID}'",
		"planId": "'${PLAN_ID}'",
		"modules": []
    },
    "targetAccount": {
        "name": "'${ACCOUNT_NAME}'",
        "countryCode": "US",
        "admin": {
            "email": "'${EMAIL_ADDRESS}'",
            "firstName": "'${FIRST_NAME}'",
            "lastName": "'${LAST_NAME}'",
            "locale": "en"
        }
    }
}

API endpoints and required scopes for account cloning

The AccountCreation Resource includes four endpoints related to account creation. 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.

The Admin API SDKs include the equivalent SDK methods for the account creation endpoints in six programming languages. See How to create an account for code examples that show how to implement account creation using SDK methods.

Endpoint	Description	Required scope
AccountCreation : CreateAssetGroupAccount	Creates a new Docusign account using the plan and modules specified in the request body.	`organization_sub_account_write`
AccountCreation: GetOrganizationPlanItems	Get information about plan items within an organization.	`organization_sub_account_read`
AccountCreation: GetSubAccountCreateProcessByAssetGroupWorkId	Get a single account creation process.	`organization_sub_account_read`
AccountCreation: GetSubAccountCreateProcessesByOrgId	Get all ongoing account creation processes for an Organization.	`organization_sub_account_read`

Account creation request processing

If an AccountCreation : CreateAssetGroupAccount request succeeds, the response looks like this:

{
  "AssetGroupWork": {
    "AssetGroupWorkId": "81bffa7c-xxxx-xxxx-beaxxxx4-9ebd34820ea3",
    "AssetGroupId": "73018b16-xxxx-xxxx-xxxx-1e51982162fd",
    "AssetGroupWorkType": "AccountAssetCreate",
    "Status": "Pending",
    "TargetAccountId": "00000000-0000-0000-0000-000000000000",
    "CreateSubAccountDetails": {
      "SubscriptionDetails": {
        "SubscriptionId": "795b8b77-xxxx-xxxx-xxxx-a57827759219",
        "PlanId": "22a84d6c-xxxx-xxxx-xxxx-1232cc3e1a5b",
        "Modules": []
      },
      "Name": "Account Name",
      "CountryCode": "US",
      "Region": "NA",
      "Site": "Demo",
      "AdminUser": {
        "EmailAddress": "example@example.com",
        "FirstName": "First",
        "LastName": "Last",
        "Locale": "en"
      },
      "BillingProfileType": 0
    },
    "Attempts": 0,
    "Message": "Awaiting Asset Group Work Job",
    "NewAssetGroupSubscriptionId": "00000000-0000-0000-0000-000000000000",
    "CreatedBy": "8cb9aa3f-xxxx-xxxx-xxxx-f6ce2e16dad1",
    "CreatedByType": 1,
    "CreatedDate": "2024-08-07T21:17:05.8912009Z",
    "UpdatedBy": "8cb9aa3f-xxxx-xxxx-xxxx-f6ce2e16dad1",
    "UpdatedByType": 1,
    "UpdatedDate": "2024-08-07T21:17:05.8912009Z"
  },
  "Message": "",
  "Success": true
}

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

Troubleshoot account creation errors

This section describes issues that can cause an account cloning process to fail. The errors may appear in the response to the AccountCreation : CreateAssetGroupAccount request.

Error code	Error message	Description
`account_creation_active_create_limit_reached`	The maximum number of accounts being created has been reached.	The maximum number of accounts that can be created at once has been reached. Currently you can only create one account at a time.
`account_creation_entitlement_disabled`	Organization does not have the required entitlement enabled.	Account creation is not enabled in this organization.
`account_creation_inactive_subscription`	Subscription provided is not active.	The account subscription for the new account is not currently active.
`account_creation_incompatible_asset_group_id`	Asset Group ID provided does not belong to this organization.	The asset group ID provided does not belong to the organization.
`account_creation_invalid_asset_requested`	Requested asset(s) does not belong to subscription.	The plan ID from the request body does not belong to the subscription.
`account_creation_invalid_inputs`	Target account details must be provided.	One or more of the values of SubAccountCreateRequest.targetAccount is missing.
`account_creation_region_cannot_be_determined_from_country`	The region cannot be determined based on the country code	An invalid value was provided for targetAccount.countryCode, and targetAccount.region was not supplied. Valid `targetAccount.countryCode` values are the two-letter ISO 3166 country codes.
`account_creation_site_cannot_be_determined`	Site cannot be determined.	An invalid value was provided for targetAccount.region. Valid values correspond to these Docusign data center regions: `NA`, `EU`, `AU`, and `CA`. Note: In the developer environment, only `NA` can be used for this value.
`account_creation_subscription_id`	Incorrect Subscription ID provided.	Invalid subscription id provided.
`account_creation_subscription_info`	Required subscription details must be provided.	The request body does not include the subscription ID or plan ID.

Next steps

For more information about account creation, see:

How to create an account
AccountCreation Resource in the API reference
Clone eSignature accounts