SOAP/REST API Best Practices Guide - DocuSign

DocuSignInformation GuideAPI Best Practices InformationThis guide provides information about the best practices to use when making calls to the DocuSignSOAP and REST APIs.SOAP and REST API Best PracticesTo maintain reliability and stability within our demo and production environments, DocuSign operateswith certain API call efficiency guidelines. To ensure effective load balance we continually monitor theAPI calls to our backend systems and we will contact developers that are putting unnecessary burdenon the system.DocuSign has imposed a default 1,000 API call per hour limit for each account. This limit ensuresresource availability for all account holders, while reducing the chances of a denial of service (DOS)attack. Exceeding this limit will result in your API calls receiving an exception for up to 60 minutes.However, the call limit is the default setting and not a service limitation. When evaluating yourintegration, if you feel the API call per hour limit will restrict your application’s usage based onanticipated volumes, please contact DocuSign to discuss further options.Additionally, your API certification review involves verifying that you do not exceed 1 status requestper unique envelope per 15 minutes for polling compliance for the following methods:SOAP API: RequestStatus, RequestStatusEx, RequestStatuses, RequestStatusesEx,RequestPDF and RequestDocumentPDFs.REST API: GET /accounts/{accountId}/envelopesFailure to do so will result in a delay in your API certification approval for the Production environmentand your application might be subject to revocation.To ensure your integration does not reach the API call limits, follow these best practices:1. Use DocuSign Connect for publishing near real-time envelope status to your web service listener.The DocuSign Connect Service Guide is included at the end of this document.2. When unable to use DocuSign Connect and you need to poll DocuSign for envelope statusupdates, use these guidelines:SOAP Requests:• Limit RequestStatus, RequestStatusEx, RequestStatuses, RequestStatusesEx, RequestPDF,RequestDocumentPDFs to 1 status request per unique envelope per 15 minutes.• Use RequestStatuses and RequestStatusesEx method calls on a changed status only.• Use RequestStatusCodes and RequestStatusChanges instead of RequestStatus (Ex) andRequestStatuses (Ex) in your poll loop. These two methods are useful in determining whichenvelopes have actually changed, match your criteria, and can be safely used in a reasonablepolling loop cycle because they are lightweight. They return the matching envelope IDs ratherthan the whole envelope status structure.• Use RequestStatusChanges, which returns a list of envelopes that have changed since thelast request and RequestStatusesEx to retrieve those envelopes.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

API Best Practices Information Guide2+• When retrieving terminal state envelopes (declined and voided), the best method is to retrievethe certificate information only.• When retrieving terminal state envelopes (completed), one RequestPDF orRequestDocumentPDFs call should be made.REST Requests:• For GET /accounts/{accountId}/envelopes requests, use the optional query strings to limitrequest checks to shorter date ranges and specific envelope statuses.3. Your system should have the ability to capture outgoing request messages and the relatedresponse messages whether using SOAP or REST. This ability need not be active all the time,but should be easily activated when needed for troubleshooting.Again, applications are not allowed to poll for envelope status more than once every 15 minutes andDocuSign discourages integrators from continuously retrieving status on envelopes that are in aterminal state (Completed, Declined, and Voided). Excessive polling will result in your API accessbeing revoked. If you need immediate notification of envelope events, DocuSign encourages you toreview envelope events or use our Connect Publisher technology, DocuSign Connect.In addition, if you have an IPS or deep packet inspection in your network, please add the followingcommon knowledge IP addresses:NA1www.docusign.net 209.67.98.12mailsea.docusign.net 209.67.98.59NA2na2.docusign.net 206.25.247.140mailch.docusign.net 206.25.247.155EU1eu1.docusign.net 206.25.247.144mailch.docusign.net 206.25.247.155DAL/DRdemo.docusign.net 209.46.117.172preview.docusign.net 209.46.117.174mailda.docusign.net 209.46.117.17Please consult our online SOAP or REST API Developer’s Guide for code snippets and detailedexplanations: http://www.docusign.com/developer-centerPost-Certification InformationAfter your API integration is certified, you need to take several actions to complete the move to theDocuSign Production environment.SOAP API Post-CertificationYou will need to perform these actions to ensure that your solution will function in the Productionenvironment.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

API Best Practices Information Guide3+1. Repoint your web services.WebServiceAccountManagementFromhttps://demo.docusign.net/api/3.0/api.asmxTohttps://www.docusign.net/api/3.0/api.asmxCredential https://demo.docusign.net/credential.asmx https://www.docusign.net/credential.asmxServicehttps://demo.docusign.net/api/3.0/dsapi.asmxhttps://www.docusign.net/api/3.0/dsapi.asmx2. Update both the API Account Number and API User ID to the production values.3. Typically, you do not need to change your Integrator Key.4. If you use the resource files or templates in the Demo Environment, transition those files them toyour Production Environment.5. For templates, the Template ID will change from the Demo environment to your Productionenvironment. Adjust your code accordingly.6. Conduct post-certification testing 3 business days prior to your go-live date to verify functionality.Envelopes used for Production testing will be credited back to your account upon verification.REST API Post-CertificationYou will need to perform these actions to ensure that your solution will function in the Productionenvironment.1. Repoint your web services.WebServiceGet AccountInfoBaseURLServiceFromhttp://{server}/restapi/{apiVersion}/accounts/{accountId}http://{server}/restapi/{apiversion}/login_informationhttps://test.docusign.net/restapi/service_informationTohttp://{server}/restapi/{apiVersion}/accounts/{accountId}http://{server}/restapi/{apiversion}/login_informationhttps://www.docusign.net/restapi/service_information2. Update both the API Account Number and API User ID to the production values.3. Typically, you do not need to change your Integrator Key.4. If you use the resource files or templates in the Demo environment, please transition them to yourProduction environment.5. For templates, the Template ID will change from the Demo environment to your Productionenvironment so adjust your code accordingly.6. Conduct post-certification testing 3 business days prior to your go-live date to verify functionality.Envelopes used for Production testing will be credited back to your account upon verification.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

Information Guide1DocuSign ConnectService Guide111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide1Copyright ©2003-2012 DocuSign, Inc. All rights reserved.DocuSign, the DocuSign logo, “Close it in the Cloud”, SecureFields, Stick-eTabs, PowerForms, "The fastest way to get a signature", The No-Paper logo, SmartEnvelopes, SmartNav, “DocuSign It!”, “The World Works Better with DocuSign”, “Your world works better with DocuSign” and ForceFields are trademarks orregistered trademarks of DocuSign, Inc. in the United States and or other countries. All other trademarks and registered trademarks are the property of theirrespective holders.Licensed under U.S. Patent 6,289,460, U.S. Patent 6,944,648, and other patents pending.No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express writtenpermission of DocuSign, Inc. Under the law, reproducing includes translating into another language or format. Every effort has been made to ensure that theinformation in this manual is accurate. DocuSign, Inc. is not responsible for printing or clerical errors. Information in this document is subject to change withoutnotice.DocuSign Connect Service Guide 08082012If you have any comments or feedback on our documentation, please send them to us at: Documentation@DocuSign.com.Summary of changes for this version:• Removed old (out-dated) limitation reference for Custom Fields.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide2Table of ContentsDocuSign Connect Service .................................................................................................................. 3Introduction .................................................................................................................................... 3Setup ................................................................................................................................................... 4Setting Up the Connect Service in Your Account ........................................................................... 4XML Information Structure ................................................................................................................... 6Key Transaction Elements ............................................................................................................. 6Form Field Data ............................................................................................................................. 7Technical Details ................................................................................................................................. 8Running the Service....................................................................................................................... 8Best Practices ................................................................................................................................ 8Connect SOAP Publishing ............................................................................................................. 8Publish Failures ............................................................................................................................. 9Manually Publishing Transactions ............................................................................................ 9Sample API Calls and Schema: ............................................................................................... 9Sample Connect Service Message .............................................................................................. 11111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide3DocuSign Connect ServiceThis guide provides a developer or business analyst with information about how the DocuSign ®Connect Service, sometimes referred to as the publisher in this document, works and discusses thedata elements that are available.IntroductionThe DocuSign Connect Service enables the sending of real-time data updates to externalapplications. These updates are generated by user transactions as the envelope progresses throughactions to completion. The Connect Service provides updated information about the status of thesetransactions and provides updates that include the actual content of document form fields; however,these updates might or might not include the document itself. The Connect Service is useful toorganizations that want a real-time view into the transactions across their user base in a centralizedlocation. This information can be customized to drive reporting or workflow specific to thatorganization’s needs.The DocuSign Connect Service acts on behalf of user accounts when transactions reach specifiedtriggers. At that point, an XML status change is sent to the customer’s system. The general flow ofevents is outlined below.Connect Service Basic FlowchartEvents/Actions DocuSign System Customer SystemEnvelopeEventRecipientActionEvents andActions arefinalized andworkflow isupdatedConnectService sendsupdated statusHTTP or XMLpost isreceived fromDocuSignAn organization’s external application can use a secure (HTTPS) ‘listener’ or a SOAP interface toaccept information from the Connect Service.• The ‘listener’ is an application that accepts XML transactions sent from the DocuSign ConnectService as events happen. This interface is not a SOAP API, such as the other interfaces inthe DocuSign System, instead the messages are sent through an HTTP POST.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide4• The SOAP interface uses a SOAP API, like the other interfaces in the DocuSign System, toreceive XML information posts.SetupIn order to use the DocuSign Connect Service, the Connect Service must be enabled in yourDocuSign account. It is not enabled by default. Once enabled, the Connect Settings page can beaccessed from the DocuSign Console.At a high level, the following steps must be taken to use the Connect Service:1) Request your account be configured to publish transaction updates. Your DocuSign AccountManager can help you with this step.2) Select the events you will use as triggers for updating the information. Events can includeseveral items such as document sent, viewed, signed, completed, etc.3) Develop an understanding of the XML data sent from the Connect Service to your application.4) Determine how your application will accept information from the Connect Service; by securelistener or by a SOAP interface.• If using a secure listener: Create an application at your HTTPS location that can acceptdata, parse the inbound XML data and utilize it. This is a web application writtenspecifically for your business.• If using a SOAP interface: Create a Retrieving Service endpoint (URL), method name,method’s argument name, and Namespace. X.509 security must be used in the SOAPheader. Refer to the Connect SOAP Publishing section for more information aboutusing the SOAP interface.Setting Up the Connect Service in Your Account1. In order to access the DocuSign Connect Services page, log on to your DocuSign account withAccount Administrator rights. From the DocuSign Console menu bar, click Preferences.The Account Preferences page appears.2. In the navigation bar on the left side of the page, under the Account Administration heading, clickFeatures. Your account features page appears.Scroll down to the DocuSign API heading and select DocuSign Connect.Enable DocuSign ConnectClick Save.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide53. In the navigation bar on the left side of the page, under the Account Administration heading, clickConnect. The DocuSign Connect Settings page appears.4. Click the Custom 1 tab or the New Custom tab to add a new setting.From this page you set the URL that the envelope information is sent to, select the events thatgenerate information and select the users integrated with the information.Note: There is a specific Salesforce tab for setting up Connect to work with Salesforce. Refer tothe DocuSign for Salesforce documentation for information about setting up Connect withSalesforce.Set the DocuSign Connect Service Settings as follows:• URL to publish: This is the web address of your listener or Retrieving Service endpoint.You need to include HTTPS:// in the web address.• Allow Envelope Publish: This option is selected by default. When this option is selected,data is sent to the web address. Clear this option to stop sending data while maintainingthe custom information.• Include Documents: Select this option to have the Connect Service send the PDFdocument along with the update XML. If you do not want to receive the PDF documentwith the updates, clear this box.• Enable Log: Select this option to enable logging for this connection. It is recommendedthat you enable this option to facilitate troubleshooting any problems. If you do not want toenable logging for this connection, clear this box. You can have a maximum of 100 activelogs for your account. The entries in active logs can be viewed by clicking the Logs tab.• Require Acknowledgement: Select this option to log posting failures. Theacknowledgement failure messages are logged in the Failures tab. When this option is111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide6selected, DocuSign will automatically attempt to repost any failures. Alternately, thecustomer can manually repost from the Failures tab. See the Publish Failures section formore information.• Sign Message with X509 Certificate: Select this option to have the message sent to thelistener signed with an X509 certificate.• Use Soap Interface: Select this option to use the SOAP interface Retrieving Service. Ifthis option is selected, you must add your Namespace for the service. Optionally, if wantDocuSign to include the X.509 certificate in the SOAP header, select Include X509Certificate.• Trigger Events: Select the trigger events for updating your system. The two left columnsof the table (envelope events and recipient events) show the DocuSign Service events thatcan trigger updates. The primary difference between envelope events and recipient eventsis that envelope events are only triggered when the envelope status changes, whilerecipient events are triggered each time information for a recipient changes.• User Accounts: Select the users associated with the trigger events. A list of all usersassociated with your account is shown. You can select All users integrated, whichselects all the current users and adds new users when they are added to the account.5. Click Save to save your configuration. You can modify this information or add another custom tabby repeating the previous steps.XML Information StructureThe DocuSign Connect Service publisher sends the status update in the body of an HTTP or SOAPXML post. The receiving web server needs to take the entire structure and parse the XML in order tomake use of the various elements available in the XML.Key Transaction ElementsThe key transaction elements available are listed below. The full XML structure contains more, butthese are the most commonly used data elements:Status Information• Sent Date/Time• Envelope Status (in process, completed)• Envelope IDEnvelope Information• Document(s)• Recipients• Tabs• Subject• Email• Custom Fields111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide7Recipient activity and information• Recipient ID(s)• Recipient Email(s)• Recipient Username(s)• Recipient Note(s)• Recipient Type (Signer, CC, CD)• Recipient Sent Date/time• Recipient Delivered Date/time• Recipient Signed Date/time• Recipient Routing Order• Recipient Status Code (created, sent, delivered, signed, declined)• Recipient Event (viewed, printed, download copy, reassigned, declined, signed)Document Information• Document Name(s)• Document ID(s)• Document Password(s)Document Content• Custom Tab Name• Custom Tab Value• Custom Tab Label• Custom Tab Required/Not Required• Custom Tab Type (text, checkbox, radio, list)• TabTypeCode (signature, initial, name, company, title, date)• Document PDF Bytes (base 64)To make use of this information your application must parse the inbound XML looking for the dataassociated with each node you are evaluating. Then the application must extract the data and place itinto the external application.Form Field DataThe DocuSign Connect Service is able to publish not only the status of the transaction, but also thevalues contained in any form fields or envelope fields in the transaction. This is useful to helpinterpret what transaction data can be updated into the external system. DocuSign supports manydifferent field types including checkbox, radio button, form field, and drop down list. These all have acommon name structure and the value from the signer can be extracted from the XML structure.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide8Technical DetailsThe XML post from DocuSign contains the EnvelopeStatus object along with DocumentPDF objects, ifthe configuration has the checkbox to include the push of the documents.The DocuSign 3.0 API WSDL file that contains definitions for both structures is located on theDocuSign website. It can be found at: https://www.docusign.net/api/3.0/api.asmx?wsdl.Running the ServiceOnce you activate the DocuSign Connect Service, DocuSign sends an XML object to the secure URLentered on the configuration page for every event selected and from every user selected. If yourapplication is not configured to accept these post messages, the DocuSign system will not return anerror.It is important that you do not turn on the DocuSign Connect Service if you have not configured alistener or Retrieving Service endpoint at the URL entered in the configuration page. Once you havethe listener set up, you may test the publisher by sending transactions and observing the behavior ofyour application.Test code for an HTTPS listener based on PHP is available from DocuSign. You can get a copy bydownloading the SDK from the DocuSign website.Best PracticesIn order to take advantage of the DocuSign Connect Service, a clear understanding of the use of theinformation needs to be understood. Be sure to ask questions such as:1. What data do you want to capture?2. Who will be accessing this information?3. What decisions or reporting will be generated?4. Should the document be pushed?These questions must be thought out and agreed in order to deploy a solution that will meet yourbusiness needs. Additionally, developing the secure listener application to have some flexibility canenable modifications to the data that is collected without requiring coding for minor adjustments. Thisfield mapping approach enables future modifications and changes that can be made by analysts.Connect SOAP PublishingThe following configurations are available in the Connect Service:• Retrieving Service endpoint (URL).• Retrieving Service method name. DocuSignConnectUpdate.• Retrieving Service method’s argument name. DocuSignEnvelopeInformation.• Retrieving Service Namespace. The default is DocuSignConnectListener.• X.509 security in the SOAP Header. DocuSign uses the standard WSE3 BinarySecurityTokenin the SoapHeader to pass the certificate.When planning the SOAP Publishing Retrieval Service, you need to do the following:1. Create a web service that has the DocuSign API as a web reference.2. Create a method in your web service that matches the Retrieving Service method name.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide93. Have a single argument on the method that matchesThe argument must be of the type DocuSignAPI.DocuSignEnvelopeInformation, whereDocuSignAPI is configurable based on the namespace used when importing the DocuSign APIweb service.4. Return the EnvelopeID passed to it, if received. Otherwise, it should return a SOAP Fault.Publish FailuresIf the Require Acknowledgement option is selected and a publication message fails to beacknowledged, the message goes back into the queue and the system will retry delivery after asuccessful acknowledgement is received. If the delivery fails a second time, the message is notreturned to the queue for sending until Connect receives a successful acknowledgement and it hasbeen at least 24 hours since the previous retry. There is a maximum of ten retries.You can always view the list of Connect publish failures by going to the Failures tab and you canmanually republish these items from the Failures tab.Additionally, you can use the API to request the Connect publish failures, see the Sample API Callsand Schema below. In cases where your listener is “down” you make one call (GetConnectFailures)to find out what messages were missed and republish those events to your listener withPublishConnectFailures. You might not even need to call either method, as the next notification eventthat Connect successfully publishes will trigger an auto-republish of any messages in the queue.If Require Acknowledgement is not selected, the delivery of the status is not guaranteed and theDocuSign System normally does not retry delivery in cases where the web server is unavailable. Acommon solution to ensure that no status changes are missed during the day is to create a nightlyquery using the DocuSign API RequestStatuses method to reconcile any events that were missed.Manually Publishing TransactionsYou can also manually publish transactions to your listening web server using the Envelope Reporttool in the DocuSign console. This is done by going to the console Preferences section and clickingEnvelope Reports under the Account Administration section. Select the search criteria for yourreports and click View, a list of envelope events that meet the search criteria is displayed. Select thePublish XML check boxes for envelopes you want to publish, select (or verify that it is selected) theApply DocuSign Connect Settings check box, and then click Publish XML.Sample API Calls and Schema:[WebMethod]public ConnectFailure[] GetConnectFailures(ConnectFailuresFilterConnectFailuresFilter)[WebMethod]public PublishConnectFailuresResult[]PublishConnectFailures(PublishConnectFailuresFilter PublishConnectFailuresFilter)The list of allowable DocuSign Connect publishstatuses.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide10This element provides the filtering criteria for requestingDocuSign Connect failures.This element provides DocuSign Connectfailures.This element provides the filtering criteria for publishingDocuSign Connect failures.111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide11This element provides the filtering criteria for requestingDocuSign Connect failures.Sample Connect Service MessageThe information below is a sample DocuSign Connect Service message in XML format. Note that thepersonal information (names and email addresses), document names, and PDFBytes information hasbeen removed from this sample.Signeruser.email@address.comUser Name12010-06-26T09:19:18.8832010-06-26T09:19:40.723Delivered::1CustomActive36452RadioTwo12TestRoleActivefb89d2ee-2876-4290-b530-ff1833d5d0d22010-06-26T09:19:45.771206-07:000aa561b8-b4d9-47e0-a615-2367971f876b111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

DocuSign Connect Service Guide12CreateEnvelopeFromTemplates TestUser Name user.email@address.com Delivered2010-06-26T09:16:21.272010-06-26T09:19:19.012010-06-26T09:19:40.747Original2010-06-26T09:16:21.27ACHolder Name ACHolder.email@address.com ACHolder LocationOnline::1Envelope Field 1FalseFalseEnvelope Field 2FalseFalsetruetruefalse1Document_Nameradio parents1DocumentPDF_NamePDFBytes_Information111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

111 Sutter Street, Suite 1000, San Francisco, CA 94104 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.