DocuSign Account Provisioning API Guide

The fastest way to get a signature.®

701 5th Avenue, Suite 4500 Seattle, WA 98104 tel 206.219.0200 fax 206.622.0736 www.docusign.com

DocuSign Account

Provisioning API Guide

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.

http://docusign.com/resources/product_resources.php�

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.


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)


• 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


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.


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>


<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>

<memberMiddleName></memberMiddleName> <memberLastName></memberLastName> <memberSuffix></memberSuffix> <isAdmin></isAdmin> <canSendEnvelopes></canSendEnvelopes> <canSignEnvelopes></canSignEnvelopes> <enableConnectForUser></enableConnectForUser> </member>  </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.


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>


<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>


701 5th Avenue, Suite 4500 Seattle, WA 98104 tel 206.219.0200 fax 206.622.0736 www.docusign.com

DocuSign Account Provisioning API Guide

Documents

Transcript of DocuSign Account Provisioning API Guide