Explore our blog

API Best Practices Guide for SBA Lending

To support the large volume of expected applicants for the Small Business Administration's new loan programs, your company may be building its own portal or considering using third-party-developed portals for sending DocuSign envelopes for SBA loan applications through the eSignature REST API. This guide outlines some of the best practices that customers or partner developers should use when using DocuSign APIs for these purposes.

API Webinars

If you are looking for help with your integration and would like to speak to an API expert, join us at an upcoming API Office Hours session. We can answer questions around the go-live process, API calls (rules and limits), authentication methods, general best practices, developer resources, and more.

Session dates/times are as follows:

API version

DocuSign strongly recommends that customers and partners use version 2.1 of the eSignature API for development.

Integration key

Treat your integration key as your application ID. It is what's used to identify a specific integration, and it's how DocuSign identifies your application. We highly recommend that customers or partners use a unique integration key for their SBA lending processes. This allows both you and DocuSign, should you need support, to monitor and track the API activity for your specific integration. Also, if you're already using APIs for your other integrations, any throttling or preventative measures that DocuSign takes on the platform side for a specific integration do not affect your other DocuSign-enabled processes. To create an integration key, log in to your DocuSign developer sandbox account, and then select the Add App/Integration Key button on the API and Keys page in DocuSign eSignature Admin..

Sending envelopes for signature:

Use of templates: Since the loan application document is a standard document as mandated by the SBA, DocuSign recommends that you implement this document as a template with the appropriate tabs within DocuSign. Cache the template ID in your client application and use it when sending envelopes for signature.
Merging data: If envelope fields need to be pre-populated with data from your loan application, you can populate them using tab data labels. Since the template and the tabs in the template do not change, DocuSign recommends that you cache the data structure of the createEnvelope call, including the relevant tab data labels, so that you do not need to fetch the template every single time.
Storing the envelope ID: The envelope ID for a loan application for a specific customer should be stored in your own system so that it can be used for subsequent API calls. Every createEnvelope call will return an envelope ID.
Checking API limits: In every API response, DocuSign will include headers that will tell you (1) what your current API calls/hour limit is, and (2) how much of that limit is remaining for the current hour. DocuSign recommends that your application read the headers and, when the limit is reached for the hour, pause all activity until the next hour. We also recommend that you log, monitor, and build alerts to notify you when the API calls/hour is getting close to the limit. That way, you can proactively reach out to your technical customer success manager (TCSM) to discuss a limit increase without blocking your business. By default, each account has 1000 API calls/hour as their limit.
Loading testing in demo: While small adjustments to your API limit can sometimes be granted without a load test, if you expect any large influx or limit increases, a load test must be done in the demo environment for us to analyze how well your application holds up, both in your own environment and its impact on DocuSign. Any request greater than a few thousand calls/hour will require you to first integrate with our demo environment, for your testing. Once we analyze your application on demo, DocuSign will be able to work with you to define appropriate limits for your specific use-case.
Gradually scale up your service: Scaling up is always a slow discovery of bottlenecks and addressing them one by one. We recommend to start slowly and ramp up day by day.

Checking envelope status

You can use any of several preferred approaches for obtaining the status of the envelope once it has been sent out for signature. All of these approaches require that the client application setup an event listener to which the DocuSign Connect service can send envelope events.

The approaches are:

Envelope-level Connect (webhook): As part of sending the envelope, a callback URL can be included with the request for the DocuSign service to call the client application whenever an event occurs for the envelope. For this specific use case, the only relevant event would be the Completed event. And we strongly recommend that the completed document, the certificate of completion (if needed), and the document fields are included with the response in the webhook.
Account-level Connect: Set up a custom account-level Connect configuration through the Account Admin UI. The Connect configuration should be set up to fire only for Completed events and include the completed document, certificate of completion (if needed), and the document fields. DocuSign recommends that you set up a separate Connect Listener endpoint for this use case.
Redirect URL post-signing: For applications that are embedding the signing experience, the most effective method to get the completion status of the envelope is to use a post-signing redirect URL. The DocuSign service automatically redirects the signer to the redirect URL after they have completed signing the document. Additional parameters on the redirect URL can be used to update the status of the envelope in the external application.
Batched envelope status calls: It is also possible to do a batched envelope status call. If you have cached the envelope IDs previously, you can also use the listStatusChanges API call infrequently (once an hour, for example), in which you can pass a set of envelope IDs, and DocuSign will return all their statuses at once. This is much more efficient than querying one at a time, though still less scalable than the previous three options. To use our batched listStatusChanges call, you can pass a set of envelope IDs with from_to_status=changed and a specific time frame to get all envelope changes.

If setting up a listener is not possible due to IT configuration challenges, your client application can use the API to request the status of an envelope. Calling the API for envelope status is not recommended more than once every four to six hours. More frequent calls will result in the available API capacity being consumed for status information. If your scenario requires real-time actions or notifications, use one of the above methods; otherwise, should you run into API limits, your integration may not be approved for limit increases.

Downloading completed documents and tag data

We've already covered this above when using Connect. For client applications that are not using Connect to receive events from DocuSign, the recommended approach is to use getEnvelope and getDocuments calls. When using getEnvelope, if you need additional data such as recipient or tab data, you can combine it into a single call using the URL parameter "Include=". See the documentation for a full list of items that can be fetched in a single call. When fetching documents, we recommend that you get documents as a ZIP file (using the Archive endpoint /envelopes/{envelopeId}/documents/archive), as this is the quickest and most efficient call. Clients should not get document and recipient data one at a time in a recursive loop.

Embedded signing in an external portal

If your application is collecting signatures from your loan applicants within the portal by embedding the DocuSign Signing UI within the application, then your application should cache the clientUserId parameter for each recipient, which was sent when initiating the envelope. Your application should make the API call to fetch the embedded signing URL only when the loan applicant is ready to sign the document, as the URL has a short-lived expiration period for security reasons.

Additional resources

DocuSign customers: Log into the Knowledge Market check out our SBA Loan resources page to help your business deploy SBA lending solutions.

Author

Mangesh Bhandarkar

Published

April 27, 2020