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 name Value Description
Path parameters
accountId string

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

Request Body

Responses

Code Description Reference
201 Created Successful response.
400 Bad Request Error encountered.

SDK Method

Users::create

Definitions Expand All | Collapse All

Users

User management

accountManagementGranular userAccountManagementGranularInformation

Describes which account management capabilities a user has.

activationAccessCode string

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

createdDateTime string

Indicates the date and time the item was created.

customSettings
[nameValue]

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

email string

The user's email address.

enableConnectForUser string

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

errorDetails errorDetails
firstName string

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

forgottenPasswordInfo forgottenPasswordInformation

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.
homeAddress addressInformation_v2

The user's physical home address.

initialsImageUri string

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

isAdmin string

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

jobTitle string
lastLogin string

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

lastName string

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

loginStatus string

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

  • password_reset
  • password_active
  • password_expired
  • password_locked
  • password_reset_failed
middleName string

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

password string
passwordExpiration string

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

permissionProfileId string
permissionProfileName string
profileImageUri string
sendActivationEmail string
sendActivationOnInvalidLogin string

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.

signatureImageUri string

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

suffixName string

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

Limit: 50 characters.

title string

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

Limit: 10 characters.

uri string
userId string

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.

userName string

The user's full name.

userProfileLastModifiedDate string

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.

userStatus string

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled
userType string
workAddress addressInformation_v2

The user's physical work address.

addressInformation_v2

address1 string

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

address2 string

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

city string
country string

Specifies the country associated with the address.

fax string
phone string
postalCode string
stateOrProvince string

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.

errorCode string

An error code associated with the error.

message string

A short error message.

forgottenPasswordInformation

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

forgottenPasswordAnswer1 string

The answer to the first forgotten password challenge question.

forgottenPasswordAnswer2 string

The answer to the second forgotten password challenge question.

forgottenPasswordAnswer3 string

The answer to the third forgotten password challenge question.

forgottenPasswordAnswer4 string

The answer to the fourth forgotten password challenge question.

forgottenPasswordQuestion1 string

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

forgottenPasswordQuestion2 string

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

forgottenPasswordQuestion3 string

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

forgottenPasswordQuestion4 string

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

group

errorDetails errorDetails
groupId string

The DocuSign group ID for the group.

groupName string

The name of the group. The search_text provided in the call automatically performs a wild card search on group_name.

groupType string

The group type.

permissionProfileId string

The ID of the permission profile associated with the group.

users
[userInfo]

nameValue

errorDetails errorDetails
name string

The name or key of a name/value pair.

originalValue string

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

value string

The value field of a name/value pair.

newUser

apiPassword string

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

createdDateTime string

Indicates the date and time the item was created.

email string
errorDetails errorDetails
permissionProfileId string
permissionProfileName string
uri string
userId string

Specifies the user ID for the new user.

userName string
userStatus string

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

newUsersDefinition

newUsers
[Users]

newUsersSummary

newUsers
[newUser]

settingsMetadata

is21CFRPart11 string

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

options
[string]
rights string
uiHint string
uiOrder string
uiType string

userAccountManagementGranularInformation

Describes which account management capabilities a user has.

canManageAdmins string

True if the user can manage admins.

canManageAdminsMetadata settingsMetadata
canManageGroups string

True if the user can manage groups.

canManageGroupsMetadata settingsMetadata
canManageSharing string
canManageSharingMetadata settingsMetadata
canManageUsers string

True if the user can manage users.

canManageUsersMetadata settingsMetadata

userInfo

activationAccessCode string
email string
errorDetails errorDetails
loginStatus string
sendActivationEmail string
uri string
userId string

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.

userName string
userStatus string

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled
userType string

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",
"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 17",
"activationAccessCode": "sample string 18",
"enableConnectForUser": "sample string 19",
"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 20",
"passwordExpiration": "sample string 21",
"lastLogin": "sample string 22",
"sendActivationEmail": "sample string 23",
"customSettings": [
{}
]
,
"profileImageUri": "sample string 24",
"userProfileLastModifiedDate": "sample string 25",
"signatureImageUri": "sample string 26",
"initialsImageUri": "sample string 27",
"jobTitle": "sample string 28"
}
]
}

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 18</activationAccessCode>
<createdDateTime>sample string 10</createdDateTime>
<customSettings>
<nameValue />
</customSettings>
<email>sample string 7</email>
<enableConnectForUser>sample string 19</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 27</initialsImageUri>
<isAdmin>sample string 4</isAdmin>
<jobTitle>sample string 28</jobTitle>
<lastLogin>sample string 22</lastLogin>
<lastName>sample string 13</lastName>
<loginStatus>sample string 20</loginStatus>
<middleName>sample string 12</middleName>
<password>sample string 8</password>
<passwordExpiration>sample string 21</passwordExpiration>
<permissionProfileId>sample string 15</permissionProfileId>
<permissionProfileName>sample string 16</permissionProfileName>
<profileImageUri>sample string 24</profileImageUri>
<sendActivationEmail>sample string 23</sendActivationEmail>
<sendActivationOnInvalidLogin>sample string 17</sendActivationOnInvalidLogin>
<signatureImageUri>sample string 26</signatureImageUri>
<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 25</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>