®

The fastest way to get a signature.

DocuSign Account

Provisioning API Guide

th
701 5 Avenue, Suite 4500
Seattle, WA 98104

tel 206.219.0200
fax 206.622.0736

www.docusign.com
 DocuSign Connect API Developer Guide ii
Stick-eTabs, DocuSign Professional, DocuSign Web, the DocuSign logo, “The fastest way to get a signature.”, and DocuSign are trademarks or registered trademarks of
DocuSign, Inc. in the United States and/or other countries. All other trademarks and registered trademarks are the property of their respective holders.
Licensed under U.S. Patent 6,289,460, U.S. Patent 6,944,648, and other patents pending.
Copyright ©2003-2010 DocuSign, Inc. All rights reserved.

DocuSignAccountProvisionAPI_201000722.pdf
 DocuSign Account Provisioning API Guide iii

Table of Contents
DocuSign Account Provisioning API Overview ............................................................................1
Basic Concepts in DocuSign Account Provisioning .................................................................................................................................... 1

Process Flow .....................................................................................................................................1

Application Initialization ........................................................................................................................................................................................ 1
Creating an Account................................................................................................................................................................................................ 2
Adding New Users to an Account...................................................................................................................................................................... 2
Activation Process .................................................................................................................................................................................................... 3

Client Implementation Guidelines.................................................................................................3

API Implementation Detail.............................................................................................................4
Authentication Methods ........................................................................................................................................................................................ 4
Common Elements................................................................................................................................................................................................... 4
Get Provisioning Info .............................................................................................................................................................................................. 4
Request ..................................................................................................................................................................................................................... 5
Response .................................................................................................................................................................................................................. 5
Create Account .......................................................................................................................................................................................................... 5
Request ..................................................................................................................................................................................................................... 6
Response .................................................................................................................................................................................................................. 7
Add Member to Account....................................................................................................................................................................................... 7
Request ..................................................................................................................................................................................................................... 7
Response .................................................................................................................................................................................................................. 8
Get Account Info ....................................................................................................................................................................................................... 8
Request ..................................................................................................................................................................................................................... 8
Response .................................................................................................................................................................................................................. 8
Authenticate Member............................................................................................................................................................................................. 9
Request ..................................................................................................................................................................................................................... 9
Response .................................................................................................................................................................................................................. 9
Check Member Exists For Account via Email ................................................................................................................................................. 9
Request ..................................................................................................................................................................................................................... 9
Response ............................................................................................................................................................................................................... 10
 DocuSign Account Provisioning API Guide 1

DocuSign Account Provisioning API Overview

The Account Provisioning API features are designed to allow an authorized external application to create accounts
and users in the DocuSign system.
The external application must be specifically authorized through use of an application token, which is generated by
DocuSign and coded into the external application. Partners developing external applications are required to treat
these tokens as confidential.
An authorized application may be required to perform certain parts of the Account Activation process during the
interview phase of the account creation process. For example, they may be required to present the DocuSign terms
of use and force the user to accept them before allowing the account creation request to be processed. The
specific parts of the Activation process that the external application is required to perform are indicated by the
configuration settings linked to the application token.
An external application may be allowed to handle all parts of the activation process, in which case the user can be
provisioned with a fully functioning DocuSign account without needing to contact DocuSign directly.
The external application is also governed by these configuration settings when it is adding new users to an existing
account.

Basic Concepts in DocuSign Account Provisioning

User – A User in the DocuSign system represents a person. Each user has an associated password.
Account – A DocuSign account is used to group Users (known as Members in their account context).
Membership – A membership represents a User’s role in an Account. Memberships have permissions associated
with them, including the ability to manage other memberships.
Price Plan – The Price Plan is associated with an account. It determines what features are available to an account
and what prices are charged for usage. Price Plans are indicated in the API by a value known as a PGP. This value is
expressed as GUID in string format.

Process Flow
Application Initialization
When the external application first connects to DocuSign, it makes an API call and provides the application token in
the call. DocuSign checks the validity of the token and responds with a message that provides necessary
parameters for the application. These parameters are detailed in DocuSign’s API documentation (go to
http://docusign.com/resources/product_resources.php to download a pdf of the guide or the SDK kit), but, for
example, include:
DistributorCode – This identifies the Distributor to which the application’s users belong.
DistributorPassword – This password is supplied on API methods to prove that the application is allowed access.
PlanGroupPlanId – This indicates the price plan that all new accounts created by the application are enrolled in.
Should users need to change their price plan they may log in to the member console to change their plan.
PlanPromoText – This is marketing copy that is displayed in the external applications user interface to inform the
user about the plan they are signing up for.
 2 DocuSign Account Provisioning API Guide

defaultConnectConfigurationId – For plans that include DocuSign Connect for Salesforce, this indicates which
standard Connect Configuration the plan receives. Changes to the configuration are made in the member console.
PasswordRuleText – This is text that explains the password rules to the user (Example: ‘Your password must be at
least six characters long.’).
These parameters are designed to ensure that there is a sufficient level of configurability in the behavior of the
external application without requiring re-coding.

Creating an Account
Once the external application is initialized, it has sufficient information to create accounts.
The information that DocuSign requires to create an account is detailed in the API specification, but on a general
level it consists of personal information (name, email address, physical address), security (password, forgotten
password question and response) and payment information (initially credit card information). This information is
sent to DocuSign along with authorization information (the Distributor Name and Password from above) and
configuration information (the PGP indicating the price plan that the account is subscribed to and, if applicable, the
default Connect configuration ID).
DocuSign evaluates this information and if it is insufficient in any way, provides a response indicating what elements
need to be corrected. If the information is sufficient, DocuSign provides a response that contains the account
credentials necessary to use the DocuSign system. These credentials must be stored in a manner that DocuSign
agrees is sufficiently secure. Depending on the configuration settings assigned to the external application, an
activation process may be required before the account can be used. Details of this process are provided below.
By default, DocuSign designates the person creating the account as the account administrator. This person will
have the authority to add new users to the account.
External applications that wish to use the DocuSign Connect for Salesforce feature must make an additional API call
to provide DocuSign with the credentials that are used when making status updates from DocuSign to Salesforce.
When these credentials are received DocuSign verifies them with Salesforce. If the verification fails an informative
response is provided to the caller. If the verification succeeds the credentials are stored in the DocuSign account
settings in the host application.

Adding New Users to an Account

Once an account has been created, a user who has account administration privileges may use the API to add new
users to the account. The information required for this is detailed in the API documentation, but generally consists
of personal information about the new user, security information, and authorization flags. The authorization flags
indicate whether the user is allowed to send envelopes, sign envelopes, or manage the account. This way an
account administrator may setup additional administrators, or ‘read-only’ users that may view completed envelopes
but not sign or send them.
This information should be accompanied by the credentials of the requesting account administrator to authorize
the request.
DocuSign evaluates this information and if it is insufficient in any way, provides a response indicating what elements
need to be corrected. If the information is sufficient, DocuSign provides a response that contains the account
credentials that are necessary to use the DocuSign system. These credentials must be stored in a manner that
DocuSign agrees is sufficiently secure.
 DocuSign Account Provisioning API Guide 3

Activation Process
DocuSign might require that new users go through an activation process before being allowed access to the
DocuSign system. This is controlled by the configuration settings associated with the application token, and
DocuSign determines, on a case by case basis, what the necessary settings are for any given application.
For a new Account Create request, the required activation process may include the following steps:
1. Email Activation – an email is sent to the email address provided in the account create request. This email
contains a link that must be clicked to verify that the requester has access to the email address.
2. Acceptance of DocuSign Terms of Use – if this is required, then after the user clicks the link in the email in
step 1, they are presented with the DocuSign Terms of Use and they are required to accept them.
3. Acceptance of Consumer Disclosure - if this is required, then after the user clicks the link in the email in step
1, they are presented with the Consumer Disclosure agreement that covers their own DocuSign account.
They are required to accept this before being allowed to access the system.
4. Password Setup – if this is required, then after the user clicks the link in the email in step 1, they are
required to choose a password and select a ‘forgotten password’ question and answer.
Steps 2 – 4 are always contingent upon step 1 – that is, if any of steps 2 – 4 are required then step 1 is required as
well. However, if step 1 is not required, then steps 2 – 4 are not required.
The goal of this process is to allow trusted partners that have already authenticated their users to provision them
with DocuSign accounts with a minimum of disruption in the user experience.

Client Implementation Guidelines

DocuSign expects that external applications that develop against this API will provide a certain level of feature
support to minimize support calls to DocuSign and provide for an acceptable user experience. This level of support
includes:
1. Secure storage of DocuSign Credentials – External applications should store these in an encrypted form
whenever possible. DocuSign may allow applications to store them unencrypted at DocuSign’s sole
discretion.
2. Secure storage of Application Token – External applications should treat the application token as
confidential information, and not disclose it to outside parties.
3. User Credential management –
• As users may log into DocuSign and change their passwords, the external application should provide a
mechanism for users to update their stored password.
• Account administrators should have the ability to remove a user’s stored DocuSign credentials in the
external application.
4. Account Create experience - When users are requesting a new DocuSign account via the external
application, the application should :
• Use platform appropriate controls for collecting and displaying of information (specifically password
masking functionality)
• Not persist any confidential information collected specifically for DocuSign account creation (i.e. Credit
Card Data)
 4 DocuSign Account Provisioning API Guide

• Display appropriate guidance at key points, specifically to include the display of DocuSign password
validation rules.
DocuSign validates supplied passwords and rejects any that do not meet the validation rules. External
applications do not need to enforce the validation rules, merely display the guidance and validation
messages.
5. Responsible API client behavior – the API client code should gracefully handle error messages and network
issues such as timeouts gracefully.
• In particular, making requests in a tight loop without user intervention or keyed off a timer event may
be considered abuse and treated as such.

API Implementation Detail

Authentication Methods
Because of the variety of use cases for the methods in this API, there are several different authentication credentials
required depending on the method being called. The credentials are listed below in the order that you will
probably encounter them in a provisioning process.
AppToken – This is used by the GetProvisioningInfo method. The AppToken is a string, provided to you by
DocuSign and is used to retrieve Account provisioning info. In particular, it enables you to get the DistributorCode
and DistributorPassword, which are used to authenticate other methods.
DistributorCode and DistributorPassword – These are used together to authenticate the CreateNewAccount
request. The CreateNewAccount response includes the credentials for the newly created Admin user. These
credentials are used for the remainder of the Account oriented methods.
AdminUserId, AdminPassword and AccountId - These three values are used to authenticate admin methods on
existing accounts. DocuSign checks the credentials to ensure that the credentials are correct and that they identify
a user who has admin rights on the account indicated by the AccountId.
UserId, Password and AccountId – These three values are used to authenticate methods that may be called by
users in an account. The user need not have administration privileges on the account. DocuSign checks the
credentials to ensure that they identify a user who is a member of the account indicated by the AccountId.

Common Elements
AdminUserId – A GUID, in string format, that identifies a User with admin privileges.
AdminPassword – The corresponding password for the Admin User.
AccountId – A GUID, in string format, that identifies an Account in DocuSign.
ErrorMessage - Response Elements typically have an ErrorMessage element that should be checked at the
completion of an API call. If this element is empty or not present, it may be assumed that the call succeeded.
UserId – A GUID, in string format, that identifies a User in DocuSign.
Password - The corresponding password for the User.

Get Provisioning Info

This method takes a DocuSign provided appToken and returns information that is required for the Create Account
method. This method is intended to allow an application to discover the provisioning information it requires
 DocuSign Account Provisioning API Guide 5

dynamically rather than having to rely on config files or hard coded values. It is not required – if you know the
proper values and wish to use some other method to persist them you may.

Request
<getProvisioningInfoRequest>
<appToken>String</appToken>
</getProvisioningInfoRequest>

Response
The Response values returned are:
distributorCode - This is a string value identifying your company.
distributorPassword – A password that corresponds to the distributorCode
pgp – This is a GUID that defines the Price Plan that is used to enroll new accounts.
planPromoText – Promotional Text that describes the price plan.
defaultConnectConfigurationId – The Default Id for Salesforce Connect setup. This is only relevant if you are
working in the Salesforce Environment.
passwordRuleText – A description of the password rules applicable to new accounts. This is provided so that you
can provide the information to your customers, so they know the password requirements to reduce the chance that
the password they choose is rejected by DocuSign.
<getProvisioningInfoResponse>
<distributorCode></distributorCode>
<distributorPassword></distributorPassword>
<pgp></pgp>
<planPromoText></planPromoText>
<defaultConnectConfigurationId></defaultConnectConfigurationId>
<passwordRuleText></passwordRuleText>
<errorMessage></errorMessage>
</getProvisioningInfoResponse>

Create Account
This method is used to create a new account in the DocuSign system. This method requires the DistributorCode
and DistributorPassword for authorization, and also requires a valid PGP (indicating the desired price plan for the
account) and credit card information.
This method creates an initial member for the account and designates that member as the account administrator.
This administrator member can then add additional members.
Depending on Provisioning Settings at DocuSign, the account may need to be activated before being used. Refer
to the Activation Process section for details on this.
Additional elements in the Request are:
accountName – The name that the newly created account should have in DocuSign.
memberEmailAddress – The email address for initial account member.
memberUserName – The full name (as it would be signed) of the member (Example: John Q. Public).
memberPassword – The password for the member. This must conform to password rules for the distributor
(available from the GetProvisioningInfo method).
memberForgottenPasswordQuestion – A question asked if the member clicks the ‘Forgot Password?’ link when
attempting to log in to the DocuSign console.
 6 DocuSign Account Provisioning API Guide

memberForgottenPasswordAnswer – The answer to the member’s forgotten password question.

memberTitle – An optional title for member.
memberFirstName – The member’s first name.
memberMiddleName – The member’s middle name. This is optional.
memberLastName – The member’s last name.
memberSuffix – A suffix for last name (Example: Jr, III, Sr, etc.). This is optional.
address1 – The street address for the account.
address2 – A second line for the street address for the account. This is optional.
city – The city for the street address for the account.
state – The state for the street address for the account.
zip – The zip or Postal Code of street address for the account.
phone – The contact phone number for account.
fax - The fax number for the account. This is optional.
referrer – Use as indicated by your account manager. This is optional.
referrerProvidedCode – Use as indicated by your account manager. This is optional.
paymentMethod – This is always CreditCard.
ccNumber – The credit card number for the account.
ccExpirationMonth – The expiration month of the credit card. This is expressed as two digits (Example: 05 = May,
12 = December).
ccExpirationYear – The expiration year of card. Always use four digits for this (Example: 2012).
ccType – The credit card type. Only Visa, Mastercard, and AmericanExpress are accepted.
ccUserName – The name on the credit card.
ccCVV2 – The Card Verification Code from the back of the card.

Request
<newAccountRequest>
<accountName></accountName>
<memberEmailAddress></memberEmailAddress>
<memberUserName></memberUserName>
<memberPassword></memberPassword>
<memberForgottenPasswordQuestion></memberForgottenPasswordQuestion>
<memberForgottenPasswordAnswer></memberForgottenPasswordAnswer>
<memberTitle></memberTitle>
<memberFirstName></memberFirstName>
<memberMiddleName></memberMiddleName>
<memberLastName></memberLastName>
<memberSuffix></memberSuffix>
<address1></address1>
<address2></address2>
<city></city>
<state></state>
<zip></zip>
<phone></phone>
<fax></fax>
<distributorCode></distributorCode>
 DocuSign Account Provisioning API Guide 7

<distributorPassword></distributorPassword>
<pgp></pgp>
<referrer></referrer>
<referrerProvidedCode></referrerProvidedCode>
<paymentMethod>CreditCard</paymentMethod>
<ccNumber></ccNumber>
<ccExpirationMonth></ccExpirationMonth>
<ccExpirationYear></ccExpirationYear>
<ccType></ccType>
<ccUserName></ccUserName>
</newAccountRequest>

Response
accountId – A GUID that identifies the account in DocuSign.
siteId - An integer alternate key for the account.
userId – A GUID that identifies the user in DocuSign.
membershipId – A GUID that identifies the user’s membership in the account.
These values are used as credentials for other API methods, so they must persist in the client application. Refer to
Implementation Guidelines above.
<newAccountResponse>
<accountId></accountId>
<siteId></siteId>
<userId></userId>
<membershipId></membershipId>
<errorMessage></errorMessage>
</newAccountResponse>

Add Member to Account

This method allows an administrator to add members to their account. The members receive an email from
DocuSign and are required to go through activation in order to use the system.
Method elements are the same as identically named elements in CreateNewAccount above with these additional
elements:
isAdmin – Indicates whether the new member is given admin rights in this account.
canSendEnvelopes – Indicates whether the new member can send new envelopes.
canSIgnEnvelopes – Indicates whether the new member can sign envelopes.
enableConnectForUser – If DocuSign Connect is provisioned for the account, setting this to true adds this new
member to list of members whose envelopes are pushed by Connect.

Request
<addMemberToAccountRequest>
<adminUserId></adminUserId>
<adminPassword></adminPassword>
<accountId></accountId>
<members>
<member>
<memberEmailAddress></memberEmailAddress>
<memberUserName></memberUserName>
<memberPassword></memberPassword>
<memberForgottenPasswordQuestion></memberForgottenPasswordQuestion>
<memberForgottenPasswordAnswer></memberForgottenPasswordAnswer>
<memberTitle></memberTitle>
<memberFirstName></memberFirstName>
 8 DocuSign Account Provisioning API Guide

<memberMiddleName></memberMiddleName>
<memberLastName></memberLastName>
<memberSuffix></memberSuffix>
<isAdmin></isAdmin>
<canSendEnvelopes></canSendEnvelopes>
<canSignEnvelopes></canSignEnvelopes>
<enableConnectForUser></enableConnectForUser>
</member>
<!-- Additional Members as desired -->
</members>
</addMemberToAccountRequest>

Response
For each Member element in response the values are identical to those returned in CreateNewAccount above. Note
that AccountId is specified in the request credentials and so is not returned with the response.
<addMemberToAccountResponse>
<members>
<member>
<userId></userId>
<membershipId></membershipId>
<errorMessage></errorMessage>
</member>
</members>
</addMemberToAccountResponse>

Get Account Info

This method is available to any member of an account and returns some status information about the account.

Request
<getAccountInfoRequest>
<userId></userId>
<password></password>
<accountId></accountId>
</getAccountInfoRequest>

Response
The elements returned are:
currentPlanId – A GUID, in string format, that identifies the account’s current Price Plan.
currentPlanName – The name of the account’s current Price Plan.
currentPlanStartDate – The date that the account subscribed to the current Price Plan.
currentPlanEndDate – The date that the current subscription ends. This value may be blank or not present, which
indicates that the current subscription continues indefinitely.
currentBillingPeriodStartDate – A billing period is a period of time, typically 30 days, that usage is calculated and
billed for. This value is the start date of the current billing period.
currentBillingPeriodEndDate – The end date of the current billing period.
currentBillingPeriodEnvelopesSent – The number of DocuSign envelopes sent in the current billing period.
currentBillingPeriodEnvelopesAllowed – The number of DocuSign envelopes that are included without additional
charge in the current billing period. Typically any envelopes sent above this amount are charged at an overage (per
use) rate.
 DocuSign Account Provisioning API Guide 9

accountSuspensionStatus – If this value is present and non-blank, it indicates the reason why the account is
currently suspended.
accountSuspensionDate – If this value is present and non-blank, it shows the date that the account was
suspended.
<getAccountInfoResponse>
<currentPlanId></currentPlanId>
<currentPlanName></currentPlanName>
<currentPlanStartDate></currentPlanStartDate>
<currentPlanEndDate></currentPlanEndDate>
<currentBillingPeriodStartDate></currentBillingPeriodStartDate>
<currentBillingPeriodEndDate></currentBillingPeriodEndDate>
<currentBillingPeriodEnvelopesSent></currentBillingPeriodEnvelopesSent>
<currentBillingPeriodEnvelopesAllowed></currentBillingPeriodEnvelopesAllowed>
<accountSuspensionStatus></accountSuspensionStatus>
<accountSuspensionDate></accountSuspensionDate>
<errorMessage></errorMessage>
</getAccountInfoResponse>

Authenticate Member
This method is used to verify that a given set of credentials identify a user in an account in the DocuSign system.
The method allows the specification of either the DocuSign userId or the email address of the user, and the
password and accountId. This method can be used to retrieve the userId of a user when they only know their email
address.

Request
<authenticateMemberRequest>
<email></email>
<userId></userId>
<password></password>
<accountId></accountId>
</authenticateMemberRequest>

Response
<authenticateMemberResponse>
<userId></userId>
<accountId></accountId>
<UserAPI></UserAPI>
<CanManageAccount></CanManageAccount>
<CanSendEnvelope></CanSendEnvelope>
<CanSendAPIRequests></CanSendAPIRequests>
<errorMessage></errorMessage>
</authenticateMemberResponse>

Check Member Exists For Account via Email

This method is useful to see if the account has a member with the specified email address. Since email addresses
are what end users use to login to the DocuSign web site and userId’s are used for API operations, this method can
be used to see if a user is a member of an account and, if so, get the userId so that other API operations (like
sending envelopes) can be conducted.

Request
email – The email address of the user being checked.
<checkAccountMemberRequest>
<adminUserId></adminUserId>
<adminPassword></adminPassword>
 10 DocuSign Account Provisioning API Guide

<accountId></accountId>
<email></email>
</checkAccountMemberRequest>

Response
status – This indicates the status of the member in the account. If the member is not active, they are not able to
use their credentials successfully.
userId – The userID that corresponds to the supplied email address.
<checkAccountMemberResponse>
<status></status>
<userId></userId>
<errorMessage></errorMessage>
</checkAccountMemberResponse>
DocuSign Account Provisioning API Guide 11

th
701 5 Avenue, Suite 4500
Seattle, WA 98104

tel 206.219.0200
fax 206.622.0736

www.docusign.com