How to create an account | Docusign

This topic demonstrates how to create a new account in your organization.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

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

Data element	Description
Admin access	The caller must be at least one of the following: A full organization administrator A delegated organization administrator See Organization Administrators for details on Docusign Admin roles.
{BASE_PATH}	A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https://<domain>/management Where <domain> is api-d.docusign.net for the developer environment and api.docusign.net for production.
{ORGANIZATION_ID}	A GUID value that identifies the the organization that contains the account to which the user will be added. Copy the value from the Organization ID field in the Organization section of the Account Profile page.

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: organization_sub_account_write and organization_sub_account_read.

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

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

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 plan and subscription information for the new account

First, get the plan and subscription information for the organization under which the new account will be created. To do this, call the AccountCreation: GetOrganizationPlanItems endpoint. Save the values of planId and subscriptionId to be used in your request body in the next step.

response=$(mktemp /tmp/response-oa.XXXXXX)
Status=$(curl --request GET ${base_path}/v2/organizations/${ORGANIZATION_ID}/planItems \
"${Headers[@]}" \
--output ${response})
echo "Results from the GET request:"
cat $response
echo ""
PLAN_ID=$(cat $response | sed 's/,/\n/g' | grep plan_id | sed 's/.*\"plan_id\":\"//g' | sed 's/\".*//g')
SUBSCRIPTION_ID=$(cat $response | sed 's/,/\n/g' | grep subscription_id | sed 's/.*\"subscription_id\":\"//g' | sed 's/\".*//g')

Step 4. Construct the request body

Next, create the request body. Set the value of id to the subscription ID returned in the previous step. The value of planId should also come from the response of the previous step. 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.

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 \
'{
    "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"
        }
    }
}
' >>$request_data

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

Now that you have constructed your API headers and request body, make a POST request to the AccountCreation : CreateAssetGroupAccount endpoint and include the request body to create the new account. Here’s how you make the call, but make sure to substitute your organization ID for {ORGANIZATION_ID}.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, and Ruby.

response=$(mktemp /tmp/response-oa.XXXXXX)
Status=$(curl --request POST ${base_path}/v2/organizations/${ORGANIZATION_ID}/assetGroups/accountCreate \
"${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.

In addition, an account activation email will be sent to the email address specified in the request body. The new account must be activated before an additional account can be provisioned. Organizations with auto-activation enabled do not require this step.

Sample response

{
  "AssetGroupWork": {
    "AssetGroupWorkId": "81bffa7c-xxxx-xxxx-beaxxxx4-9ebd34820ea3",
    "AssetGroupId": "73018b16-xxxx-xxxx-xxxx-1e51982162fd",
    "AssetGroupWorkType": "AccountAssetCreate",
    "Status": "Pending",
    "TargetAccountId": "00000000-xxxx-xxxx-xxxx-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
}

Next steps

Run this code example from our Quickstart or launcher projects: C#, Java, Node.js, PHP, Python, or Ruby.
See How to clone an account.
See how to Go-Live with a completed app and find the base path for API calls in the production environment.