Users: create

Adds new users to an account.

The body of this request is an array of Users objects. For each new user, you must provide at least the userName and an email.

The userSettings property is a name/value list that specifies the actions users can perform. In the example below, Tal Mason will be able to send envelopes, and the activation email will be in French because the locale is set to fr.

POST /restapi/v2/accounts/{accountId}/users
Content-Type: application/json
{
  "newUsers": [
    {
      "userName": "Claire Horace",
      "email": "claire@example.com.com"
    },
    {
      "userName": "Tal Mason",
      "email": "tal@example.com.com",
      "userSettings": [
        {
          "name": "canSendEnvelope",
          "value": "true"
        },
        {
          "name": "locale",
          "value": "fr"
        }
      ]
    }
  ]
}

A successful response is a newUsers array with information about the newly created users. If there was problem creating a user, that entry will contain an errorDetails property that describes what went wrong.

{
  "newUsers": [
    {
      "userId": "e064a4fc-c0da-c0c0-95fa-8bac87ede98a",
      "uri": "/users/e064a4fc-c0da-c0c0-95fa-8bac87ede98a",
      "email": "claire@example.com",
      "userName": "Claire Horace",
      "createdDateTime": "0001-01-01T08:00:00.0000000Z",
      "errorDetails": {
        "errorCode": "USER_ALREADY_EXISTS_IN_ACCOUNT",
        "message": "Username and email combination already exists for this account."
      }
    },
    {
      "userId": "a0e6c64b-feed-cafe-9af0-805ff3c8cffd",
      "uri": "/users/a0e6c64b-feed-cafe-9af0-805ff3c8cffd",
      "email": "tal@example.com",
      "userName": "Tal Mason",
      "userStatus": "ActivationSent",
      "createdDateTime": "2017-09-15T05:54:36.1265683Z"
    }
  ]
}

User Settings

User settings specify the capabilities a newly created user will have.

Name Value Authorization Requried Description
allowBulkRecipients Boolean Admin When true, this user can use the bulk send functionality.
allowRecipientLanguageSelection Boolean Admin When true, this user can set the language used in the standard email format for a recipient when creating an envelope.
allowSendOnBehalfOf Boolean Admin When true, this user can send envelopes 'on behalf of' other users through the API.
apiAccountWideAccess Boolean Admin When true, this user can send and manage envelopes for the entire account using the DocuSign API.
canEditSharedAddressBook String Admin Sets the address book usage and management rights for the user. Possible values:
  • none
  • use_only_shared
  • use_private_and_shared
  • share
canManageAccount Boolean Admin & not setting for self When true, this user can manage account settings, manage user settings, add users, and remove users.
canManageTemplates String Admin & not setting for self Sets the template usage and management rights for the user. Possible values:
  • none
  • use
  • create
  • share
canSendAPIRequests Boolean Admin & account setting usesAPI is set Only needed if integrator key is not used. When true, this user can send and manage envelopes using the DocuSign API.
canSendEnvelope Boolean Admin & not setting for self When true, this user can send envelopes though the DocuSign Console.
enableDSPro Boolean SysAdmin When true, this user can send and manage envelopes from the DocuSign Desktop Client.
enableSequentialSigningAPI Boolean SysAdmin When true, this user can define the routing order of recipients for envelopes sent using the DocuSign API.
enableSequentialSigningUI Boolean SysAdmin When true, this user can define the routing order of recipients while sending documents for signature.
enableSignerAttachments Boolean Admin When true, this user can add requests for attachments from signers while sending documents.
enableSignOnPaperOverride Boolean Admin When true, this user can override the account setting that determines if signers may sign their documents on paper as an option to signing electronically.
enableTransactionPoint Boolean SysAdmin When true, this user can select an envelope from their member console and upload the envelope documents to TransactionPoint.
enableVaulting Boolean Admin When true, this user can use electronic vaulting for documents.
locale String Admin Sets the default language for the user. The supported languages are:
  • Chinese Simplified: zh_CN
  • Chinese Traditional: zh_TW
  • Dutch: nl
  • English US: en
  • French: fr
  • German: de
  • Italian: it
  • Japanese: ja
  • Korean: ko
  • Portuguese: pt
  • Portuguese (Brazil): pt_BR
  • Russian: ru
  • Spanish: es
powerFormAdmin Boolean Admin When true, this user can create, manage and download the PowerForms documents.
powerFormUser Boolean Admin When true, this user can view and download PowerForms documents.
selfSignedRecipientEmailDocument String Admin Sets how self-signed documents are presented to the email recipients. This can only be changed if the selfSignedRecipientEmailDocumentUserOverride account setting is true. This setting overrides the account setting. Possibe values are:
  • include_pdf: A PDF of the completed document is attached to the email.
  • include_link: A secure link to the self-signed documents is included in the email.
vaultingMode String Admin Sets the electronic vaulting mode for the user. Possible values:
  • none
  • estored
  • electronic_original

Request

HTTP request

POST /v2/accounts/{accountId}/users

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

The external account number (int) or account ID Guid.

Request Body

newUsersDefinition

Responses

CodeDescriptionReference
201

Successful response.

newUsersSummary
400

Error encountered.

errorDetails

SDK Method

Users::create

Definitions

addressInformation_v2

address1string

First Line of the address. Maximum length: 100 characters.

address2string

Second Line of the address. Maximum length: 100 characters.

citystring

countrystring

Specifies the country associated with the address.

faxstring

phonestring

postalCodestring

stateOrProvincestring

The state or province associated with the address.

errorDetails

This object describes errors that occur. It is only valid for responses, and ignored in requests.

errorCodestring

An error code associated with the error.

messagestring

A short error message.

forgottenPasswordInformation

A complex element that has up to four Question/Answer pairs for forgotten password information.

forgottenPasswordAnswer1string

The answer to the first forgotten password challenge question.

forgottenPasswordAnswer2string

The answer to the second forgotten password challenge question.

forgottenPasswordAnswer3string

The answer to the third forgotten password challenge question.

forgottenPasswordAnswer4string

The answer to the fourth forgotten password challenge question.

forgottenPasswordQuestion1string

The first challenge question presented to a user who has forgotten their password.

forgottenPasswordQuestion2string

The second challenge question presented to a user who has forgotten their password.

forgottenPasswordQuestion3string

The third challenge question presented to a user who has forgotten their password.

forgottenPasswordQuestion4string

The fourth challenge question presented to a user who has forgotten their password.

group

Information about groups.

errorDetailserrorDetails

groupIdstring

The DocuSign group ID for the group.

groupNamestring

The name of the group.

groupTypestring

The group type.

permissionProfileIdstring

The ID of the permission profile associated with the group.

users[userInfo]

List of users in the group.

nameValue

errorDetailserrorDetails

namestring

The name or key of a name/value pair.

originalValuestring

The initial value of the tab when it was sent to the recipient.

valuestring

The value field of a name/value pair.

newUser

apiPasswordstring

Contains a token that can be used for authentication in API calls instead of using the user name and password.

createdDateTimestring

Indicates the date and time the item was created.

emailstring

errorDetailserrorDetails

permissionProfileIdstring

permissionProfileNamestring

uristring

userIdstring

Specifies the user ID for the new user.

userNamestring

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

newUsersDefinition

newUsers[Users]

newUsersSummary

newUsers[newUser]

settingsMetadata

is21CFRPart11string

When set to true, indicates that this module is enabled on the account.

options[array]

rightsstring

uiHintstring

uiOrderstring

uiTypestring

userAccountManagementGranularInformation

Describes which account management capabilities a user has.

canManageAccountSecuritySettingsstring

canManageAccountSecuritySettingsMetadatasettingsMetadata

canManageAccountSettingsstring

canManageAccountSettingsMetadatasettingsMetadata

canManageAdminsstring

True if the user can manage admins.

canManageAdminsMetadatasettingsMetadata

canManageGroupsstring

True if the user can manage groups.

canManageGroupsMetadatasettingsMetadata

canManageReportingstring

canManageReportingMetadatasettingsMetadata

canManageSharingstring

canManageSharingMetadatasettingsMetadata

canManageSigningGroupsstring

canManageSigningGroupsMetadatasettingsMetadata

canManageUsersstring

True if the user can manage users.

canManageUsersMetadatasettingsMetadata

userInfo

activationAccessCodestring

emailstring

errorDetailserrorDetails

loginStatusstring

sendActivationEmailstring

uristring

userIdstring

The user ID of the user being accessed. Generally this is the user ID of the authenticated user, but if the authenticated user is an Admin on the account, this may be another user the Admin user is accessing. Note: For GET /v2/accounts/{accountId}/envelopes user_id query parameter is not implemented and should not be used.

userNamestring

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

userTypestring

Users

User management

accountManagementGranularuserAccountManagementGranularInformation

Describes which account management capabilities a user has.

activationAccessCodestring

The activation code the new user must enter when activating their account.

countryCodestring

createdDateTimestring

Indicates the date and time the item was created.

customSettings[nameValue]

The name/value pair information for the user custom setting.

emailstring

The user's email address.

enableConnectForUserstring

Specifies whether the user is enabled for updates from DocuSign Connect. Valid values: true or false.

errorDetailserrorDetails

firstNamestring

The user's first name. Maximum Length: 50 characters.

forgottenPasswordInfoforgottenPasswordInformation

A complex element that has up to four Question/Answer pairs for forgotten password information.

groupList[group]

A list of the group information for groups to add the user to. Group information can be found by calling [ML:GET group information]. The only required parameter is groupId.

The parameters are:

  • groupId - The DocuSign group ID for the group.
  • groupName - The name of the group
  • permissionProfileId - The ID of the permission profile associated with the group.
  • groupType - The group type.

homeAddressaddressInformation_v2

The user's physical home address.

initialsImageUristring

Contains the URI for an endpoint that you can use to retrieve the initials image.

isAdminstring

Determines if the feature set is actively set as part of the plan.

lastLoginstring

The date-time when the user last logged on to the system.

lastNamestring

The user's last name. Maximum Length: 50 characters.

loginStatusstring

Shows the current status of the user's password. Possible values are:

  • password_reset
  • password_active
  • password_expired
  • password_locked
  • password_reset_failed

middleNamestring

The user's middle name. Limit: 50 characters.

passwordstring

passwordExpirationstring

If password expiration is enabled, the date-time when the user's password expires.

permissionProfileIdstring

permissionProfileNamestring

profileImageUristring

sendActivationEmailstring

sendActivationOnInvalidLoginstring

When set to true, specifies that an additional activation email is sent to the user if they fail a log on before activating their account.

signatureImageUristring

Contains the URI for an endpoint that you can use to retrieve the signature image.

subscribestring

suffixNamestring

The suffix for the user's name, such as Jr, IV, PhD, etc.

Limit: 50 characters.

titlestring

Salutation for the user, such as Ms, Dr, Capt., etc.

Limit: 10 characters.

uristring

userIdstring

The user ID of the user being accessed. Generally this is the user ID of the authenticated user, but if the authenticated user is an Admin on the account, this may be another user the Admin user is accessing. Note: For GET /v2/accounts/{accountId}/envelopes user_id query parameter is not implemented and should not be used.

userNamestring

The user's full name.

userProfileLastModifiedDatestring

The date-time when the user's profile was last modified.

userSettings[nameValue]

The collection of settings that describes the actions a user can perform. See User Settings for a list of available settings.

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

userTypestring

workAddressaddressInformation_v2

The user's physical work address.

Examples

Generic JSON Request/Response

Request
{
  "newUsers": [
    {
      "userName": "sample string 1",
      "userId": "sample string 2",
      "userType": "sample string 3",
      "isAdmin": "sample string 4",
      "userStatus": "sample string 5",
      "uri": "sample string 6",
      "email": "sample string 7",
      "password": "sample string 8",
      "title": "sample string 9",
      "createdDateTime": "sample string 10",
      "firstName": "sample string 11",
      "middleName": "sample string 12",
      "lastName": "sample string 13",
      "suffixName": "sample string 14",
      "permissionProfileId": "sample string 15",
      "permissionProfileName": "sample string 16",
      "countryCode": "sample string 17",
      "subscribe": "sample string 18",
      "userSettings": [
        {}
      ],
      "accountManagementGranular": {
        "canManageUsers": "sample string 1",
        "canManageAdmins": "sample string 2",
        "canManageGroups": "sample string 3",
        "canManageSharing": "sample string 4",
        "canManageUsersMetadata": {
          "rights": "sample string 1",
          "uiHint": "sample string 2",
          "uiType": "sample string 3",
          "uiOrder": "sample string 4",
          "is21CFRPart11": "sample string 5",
          "options": [
            "sample string 1"
          ]
        },
        "canManageAdminsMetadata": {},
        "canManageGroupsMetadata": {},
        "canManageSharingMetadata": {}
      },
      "sendActivationOnInvalidLogin": "sample string 19",
      "activationAccessCode": "sample string 20",
      "enableConnectForUser": "sample string 21",
      "forgottenPasswordInfo": {
        "forgottenPasswordQuestion1": "sample string 1",
        "forgottenPasswordAnswer1": "sample string 2",
        "forgottenPasswordQuestion2": "sample string 3",
        "forgottenPasswordAnswer2": "sample string 4",
        "forgottenPasswordQuestion3": "sample string 5",
        "forgottenPasswordAnswer3": "sample string 6",
        "forgottenPasswordQuestion4": "sample string 7",
        "forgottenPasswordAnswer4": "sample string 8"
      },
      "groupList": [
        {
          "groupId": "sample string 1",
          "groupName": "sample string 2",
          "permissionProfileId": "sample string 3",
          "groupType": "sample string 4",
          "users": [
            {
              "userName": "sample string 1",
              "userId": "sample string 2",
              "email": "sample string 3",
              "userType": "sample string 4",
              "userStatus": "sample string 5",
              "uri": "sample string 6",
              "loginStatus": "sample string 7",
              "sendActivationEmail": "sample string 8",
              "activationAccessCode": "sample string 9"
            }
          ]
        }
      ],
      "workAddress": {
        "address1": "sample string 1",
        "address2": "sample string 2",
        "city": "sample string 3",
        "stateOrProvince": "sample string 4",
        "postalCode": "sample string 5",
        "phone": "sample string 6",
        "fax": "sample string 7",
        "country": "sample string 8"
      },
      "homeAddress": {},
      "loginStatus": "sample string 22",
      "passwordExpiration": "sample string 23",
      "lastLogin": "sample string 24",
      "sendActivationEmail": "sample string 25",
      "customSettings": [
        {}
      ],
      "profileImageUri": "sample string 26",
      "userProfileLastModifiedDate": "sample string 27",
      "signatureImageUri": "sample string 28",
      "initialsImageUri": "sample string 29",
      "jobTitle": "sample string 30"
    }
  ]
}
Response
{
  "newUsers": [
    {
      "userId": "sample string 1",
      "uri": "sample string 2",
      "apiPassword": "sample string 3",
      "email": "sample string 4",
      "userName": "sample string 5",
      "permissionProfileId": "sample string 6",
      "permissionProfileName": "sample string 7",
      "userStatus": "sample string 8",
      "createdDateTime": "sample string 9",
      "errorDetails": {
        "errorCode": "sample string 1",
        "message": "sample string 2"
      }
    }
  ]
}
Generic XML Request/Response

Request
<newUsersDefinition xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <newUsers>
    <userInformation>
      <accountManagementGranular>
        <canManageAdmins>sample string 2</canManageAdmins>
        <canManageAdminsMetadata />
        <canManageGroups>sample string 3</canManageGroups>
        <canManageGroupsMetadata />
        <canManageSharing>sample string 4</canManageSharing>
        <canManageSharingMetadata />
        <canManageUsers>sample string 1</canManageUsers>
        <canManageUsersMetadata>
          <is21CFRPart11>sample string 5</is21CFRPart11>
          <options>
            <string>sample string 1</string>
          </options>
          <rights>sample string 1</rights>
          <uiHint>sample string 2</uiHint>
          <uiOrder>sample string 4</uiOrder>
          <uiType>sample string 3</uiType>
        </canManageUsersMetadata>
      </accountManagementGranular>
      <activationAccessCode>sample string 20</activationAccessCode>
      <countryCode>sample string 17</countryCode>
      <createdDateTime>sample string 10</createdDateTime>
      <customSettings>
        <nameValue />
      </customSettings>
      <email>sample string 7</email>
      <enableConnectForUser>sample string 21</enableConnectForUser>
      <firstName>sample string 11</firstName>
      <forgottenPasswordInfo>
        <forgottenPasswordAnswer1>sample string 2</forgottenPasswordAnswer1>
        <forgottenPasswordAnswer2>sample string 4</forgottenPasswordAnswer2>
        <forgottenPasswordAnswer3>sample string 6</forgottenPasswordAnswer3>
        <forgottenPasswordAnswer4>sample string 8</forgottenPasswordAnswer4>
        <forgottenPasswordQuestion1>sample string 1</forgottenPasswordQuestion1>
        <forgottenPasswordQuestion2>sample string 3</forgottenPasswordQuestion2>
        <forgottenPasswordQuestion3>sample string 5</forgottenPasswordQuestion3>
        <forgottenPasswordQuestion4>sample string 7</forgottenPasswordQuestion4>
      </forgottenPasswordInfo>
      <groupList>
        <group>
          <groupId>sample string 1</groupId>
          <groupName>sample string 2</groupName>
          <groupType>sample string 4</groupType>
          <permissionProfileId>sample string 3</permissionProfileId>
          <users>
            <userInfo>
              <activationAccessCode>sample string 9</activationAccessCode>
              <email>sample string 3</email>
              <loginStatus>sample string 7</loginStatus>
              <sendActivationEmail>sample string 8</sendActivationEmail>
              <uri>sample string 6</uri>
              <userId>sample string 2</userId>
              <userName>sample string 1</userName>
              <userStatus>sample string 5</userStatus>
              <userType>sample string 4</userType>
            </userInfo>
          </users>
        </group>
      </groupList>
      <homeAddress />
      <initialsImageUri>sample string 29</initialsImageUri>
      <isAdmin>sample string 4</isAdmin>
      <jobTitle>sample string 30</jobTitle>
      <lastLogin>sample string 24</lastLogin>
      <lastName>sample string 13</lastName>
      <loginStatus>sample string 22</loginStatus>
      <middleName>sample string 12</middleName>
      <password>sample string 8</password>
      <passwordExpiration>sample string 23</passwordExpiration>
      <permissionProfileId>sample string 15</permissionProfileId>
      <permissionProfileName>sample string 16</permissionProfileName>
      <profileImageUri>sample string 26</profileImageUri>
      <sendActivationEmail>sample string 25</sendActivationEmail>
      <sendActivationOnInvalidLogin>sample string 19</sendActivationOnInvalidLogin>
      <signatureImageUri>sample string 28</signatureImageUri>
      <subscribe>sample string 18</subscribe>
      <suffixName>sample string 14</suffixName>
      <title>sample string 9</title>
      <uri>sample string 6</uri>
      <userId>sample string 2</userId>
      <userName>sample string 1</userName>
      <userProfileLastModifiedDate>sample string 27</userProfileLastModifiedDate>
      <userSettings>
        <nameValue />
      </userSettings>
      <userStatus>sample string 5</userStatus>
      <userType>sample string 3</userType>
      <workAddress>
        <address1>sample string 1</address1>
        <address2>sample string 2</address2>
        <city>sample string 3</city>
        <country>sample string 8</country>
        <fax>sample string 7</fax>
        <phone>sample string 6</phone>
        <postalCode>sample string 5</postalCode>
        <stateOrProvince>sample string 4</stateOrProvince>
      </workAddress>
    </userInformation>
  </newUsers>
</newUsersDefinition> 
Response
<newUsersSummary xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <newUsers>
    <newUser>
      <apiPassword>sample string 3</apiPassword>
      <createdDateTime>sample string 9</createdDateTime>
      <email>sample string 4</email>
      <errorDetails>
        <errorCode>sample string 1</errorCode>
        <message>sample string 2</message>
      </errorDetails>
      <permissionProfileId>sample string 6</permissionProfileId>
      <permissionProfileName>sample string 7</permissionProfileName>
      <uri>sample string 2</uri>
      <userId>sample string 1</userId>
      <userName>sample string 5</userName>
      <userStatus>sample string 8</userStatus>
    </newUser>
  </newUsers>
</newUsersSummary> 
}} />