DocuSign Momentum 2018DocuSign Momentum 2018
{"api":"esign_rest","category":"reference"}

Users Category

Use the Users category to manage the users in your accounts.

You can:

  • Set custom user settings.
  • Manage a users profile.
  • Add delete users.
  • Add and delete the intials and signature images for a user.

UserCustomSettings

Users' custom settings

MethodDescription
list
GET /v2/accounts/{accountId}/users/{userId}/custom_settings

Retrieves a list of custom user settings for a single user.

Custom settings provide a flexible way to store and retrieve custom user information that can be used in your own system.

Note: Custom user settings are not the same as user account settings.

###Getting Grouped Custom User Settings###

If the custom user settings you want to retrieve are grouped, you must include the following information in the header, after Content-Type, in the request:

X-DocuSign-User-Settings-Key:group_name

Where the group_name is your designated name for the group of customer user settings.

If the extra header information is not included, only the custom user settings that were added without a group are retrieved.

update
PUT /v2/accounts/{accountId}/users/{userId}/custom_settings

Adds or updates custom user settings for the specified user.

Note: Custom user settings are not the same as user account settings.

Custom settings provide a flexible way to store and retrieve custom user information that you can use in your own system.

Important: There is a limit on the size for all the custom user settings for a single user. The limit is 4,000 characters, which includes the XML and JSON structure for the settings.

Grouping Custom User Settings

You can group custom user settings when adding them. Grouping allows you to retrieve settings that are in a specific group, instead of retrieving all the user custom settings.

To group custom user settings, add the following information in the header, after Content-Type:

X-DocuSign-User-Settings-Key:group_name

Where the group_name is your designated name for the group of customer user settings. Grouping is shown in the Example Request Body below.

When getting or deleting grouped custom user settings, you must include the extra header information.

Grouping custom user settings is not required and if the extra header information is not included, the custom user settings are added normally and can be retrieved or deleted without including the additional header.

delete
DELETE /v2/accounts/{accountId}/users/{userId}/custom_settings

Deletes the specified custom user settings for a single user.

###Deleting Grouped Custom User Settings###

If the custom user settings you want to delete are grouped, you must include the following information in the header, after Content-Type, in the request:

X-DocuSign-User-Settings-Key:group_name

Where the group_name is your designated name for the group of customer user settings.

If the extra header information is not included, only the custom user settings that were added without a group are deleted.

UserProfiles

Users' profiles

MethodDescription
get
GET /v2/accounts/{accountId}/users/{userId}/profile

Retrieves the user profile information, the privacy settings and personal information (address, phone number, etc.) for the specified user.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the specified account.

update
PUT /v2/accounts/{accountId}/users/{userId}/profile

Updates the user's detail information, profile information, privacy settings, and personal information in the user ID card.

You can also change a user's name by changing the information in the userDetails property. When changing a user's name, you can either change the information in the userName property OR change the information in firstName, middleName, lastName, suffixName, and title properties. Changes to firstName, middleName, lastName, suffixName, and title properties take precedence over changes to the userName property.

Users

User management

MethodDescription
list
GET /v2/accounts/{accountId}/users

Retrieves the list of users for the specified account.

The response returns the list of users for the account along with the information about the result set. If the additional_info query was added to the endpoint and set to true, the full user information is returned for each user

updateList
PUT /v2/accounts/{accountId}/users

create
POST /v2/accounts/{accountId}/users

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

delete
DELETE /v2/accounts/{accountId}/users

This closes one or more user records in the account. Users are never deleted from an account, but closing a user prevents them from using account functions.

The response returns whether the API execution was successful (200 - OK) or if it failed. The response contains a user structure similar to the request and includes the user changes. If an error occurred during the DELETE operation for any of the users, the response for that user contains an errorDetails node with errorCode and message properties.

get
GET /v2/accounts/{accountId}/users/{userId}

Retrieves the user information for the specified user.

To return additional user information that details the last login date, login status, and the user's password expiration date, set the optional additional_info query string parameter to true.

update
PUT /v2/accounts/{accountId}/users/{userId}

getProfileImage
GET /v2/accounts/{accountId}/users/{userId}/profile/image

Retrieves the user profile picture for the specified user. The image is returned in the same format as uploaded.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the specified account.

If successful, the response returns a 200 - OK and the user profile image.

updateProfileImage
PUT /v2/accounts/{accountId}/users/{userId}/profile/image

Updates the user profile image by uploading an image to the user profile.

The supported image formats are: gif, png, jpeg, and bmp. The file must be less than 200K. For best viewing results, DocuSign recommends that the image is no more than 79 pixels wide and high.

deleteProfileImage
DELETE /v2/accounts/{accountId}/users/{userId}/profile/image

Deletes the user profile image from the specified user's profile.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the specified account.

getSettings
GET /v2/accounts/{accountId}/users/{userId}/settings

Retrieves a list of the account settings and email notification information for the specified user.

The response returns the account setting name/value information and the email notification settings for the specified user. For more information about the different user settings, see the [ML:userSettings list].

updateSettings
PUT /v2/accounts/{accountId}/users/{userId}/settings

Updates the account settings list and email notification types for the specified user.

UserSignatures

Users' signatures

MethodDescription
list
GET /v2/accounts/{accountId}/users/{userId}/signatures

Retrieves the signature definitions for the specified user.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

updateList
PUT /v2/accounts/{accountId}/users/{userId}/signatures

create
POST /v2/accounts/{accountId}/users/{userId}/signatures

Adds a user signature image and/or user initials image to the specified user.

The userId property specified in the endpoint must match the authenticated user's userId and the user must be a member of the account.

The rules and processes associated with this are:

  • If Content-Type is set to application/json, then the default behavior for creating a default signature image, based on the name and a DocuSign font, is used.
  • If Content-Type is set to multipart/form-data, then the request must contain a first part with the user signature information, followed by parts that contain the images.

For each Image part, the Content-Disposition header has a "filename" value that is used to map to the signatureName and/or signatureInitials properties in the JSON to the image.

For example: Content-Disposition: file; filename="Ron Test20121127083900"

If no matching image (by filename value) is found, then the image is not set. One, both, or neither of the signature and initials images can be set with this call.

The Content-Transfer-Encoding: base64 header, set in the header for the part containing the image, can be set to indicate that the images are formatted as base64 instead of as binary.

If successful, 200-OK is returned, and a JSON structure containing the signature information is provided, note that the signatureId can change with each API POST, PUT, or DELETE since the changes to the signature structure cause the current signature to be closed, and a new signature record to be created.

get
GET /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}

Retrieves the structure of a single signature with a known signature name.

The userId specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

update
PUT /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}

Creates, or updates, the signature font and initials for the specified user. When creating a signature, you use this resource to create the signature name and then add the signature and initials images into the signature.

Note: This will also create a default signature for the user when one does not exist.

The userId property specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

delete
DELETE /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}

Removes the signature information for the user.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

getImage
GET /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}/{imageType}

Retrieves the specified initials image or signature image for the specified user. The image is returned in the same format as uploaded. In the request you can specify if the chrome (the added line and identifier around the initial image) is returned with the image.

The userId property specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

Note: Older envelopes might only have chromed images. If getting the non-chromed image fails, try getting the chromed image.

updateImage
PUT /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}/{imageType}

Updates the user signature image or user initials image for the specified user. The supported image formats for this file are: gif, png, jpeg, and bmp. The file must be less than 200K.

The userId property specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

deleteImage
DELETE /v2/accounts/{accountId}/users/{userId}/signatures/{signatureId}/{imageType}

Deletes the specified initials image or signature image for the specified user.

The function deletes one or the other of the image types, to delete both the initials image and signature image you must call the endpoint twice.

The userId parameter specified in the endpoint must match the authenticated user's user ID and the user must be a member of the account.

The signatureId parameter accepts a signature ID or a signature name. DocuSign recommends you use signature ID (signatureId), since some names contain characters that do not properly encode into a URL. If you use the user name, it is likely that the name includes spaces. In that case, URL encode the name before using it in the endpoint.

For example encode "Bob Smith" as "Bob%20Smith".

Contacts

MethodDescription
update
PUT /v2/accounts/{accountId}/contacts

create
POST /v2/accounts/{accountId}/contacts

deleteList
DELETE /v2/accounts/{accountId}/contacts

get
GET /v2/accounts/{accountId}/contacts/{contactId}

delete
DELETE /v2/accounts/{accountId}/contacts/{contactId}