Efficiency score factors

Your integration had some API calls blocked after exceeding the hourly (3,000 calls per hour, by default) or burst (500 calls per 30 seconds) limit. These limits apply to the total number of calls from all integrations associated with your account.

After exceeding either limit, you will be locked out of making API calls until the next window of time starts. Making more API calls after being blocked can decrease your efficiency score, especially if a high percentage of your total calls are blocked.

Recommendations

Look for ways to reduce the number of API calls your app makes per 30 seconds or per hour:

• Do not repeat calls within the current window.
• Monitor your application’s API usage by checking the X-RateLimit-Limit and X-BurstLimit-Limit headers, included with most Docusign REST API responses. If you are approaching the limit for calls per hour or calls per 30 seconds, delay nonessential calls until the next window starts.
• After optimizing your apps, if your account still regularly exceeds the hourly limit, you may be able to increase it via the API limit management feature.

Your integration had some API calls blocked after exceeding the Docusign API call burst limit (500 calls per 30 seconds). The burst limit applies to the total number of calls from all integrations associated with your account.

Each time you exceed the limit, you will be locked out of making API calls until the next 30-second window starts. Making more API calls after being blocked can decrease your efficiency score.

Recommendations

Look for ways to reduce the number of API calls your app makes per 30 seconds:

• Do not repeat calls within the current window.
• Monitor your application’s API usage by checking the X-BurstLimit-Limit headers included with most Docusign REST API responses. If you are approaching the limit of 500 calls per 30 seconds, delay nonessential calls until the next window starts.
• If you are implementing bulk sending scenarios, make sure that you are using the bulk send feature and, if you have a large number of bulk send recipients, make sure that they will not answer simultaneously.

Your integration had some API calls blocked after exceeding the hourly API call limit (3,000 calls per hour, by default). The call limit applies to the total number of calls from all integrations associated with your account.

Each time you exceed the limit, you will be locked out of making API calls until the next hour window starts. Making more API calls after being blocked can decrease your efficiency score.

Recommendations

Look for ways to reduce the number of API calls your app makes per hour:

• Do not repeat calls within the current window.
• Monitor your application’s API usage by checking the X-RateLimit-Limit headers included with most Docusign REST API responses. If you are approaching the calls per hour limit, delay nonessential calls until the next window starts.
• Rather than repeatedly polling to track your envelope status, use Docusign Connect and a listener to subscribe to receive updates.
• After optimizing your apps, if your account still regularly exceeds the hourly limit, you may be able to increase it via the API limit management feature.

Your integration is making an excessive number of requests to retrieve documents from envelopes. This reflects calls to the eSignature REST API EnvelopeDocuments:get endpoint and corresponding SDK methods, which retrieve documents from an envelope.

Recommendations

• As a best practice, try to make fewer API calls per envelope. This includes envelope creation, any updates, and tracking.
• Instead of making multiple calls to EnvelopeDocuments:get or a corresponding SDK method to retrieve all documents from an envelope, you can retrieve them all in a single call by setting the documentId parameter to combined or archive.

Your integration is making an excessive number of requests to envelope APIs. This measures all envelope API calls except those to create, delete, get, or update templates.

Recommendations

As a best practice, try to make fewer API calls per envelope. This includes envelope creation, any updates, and tracking. You can streamline your envelope process by:

• When creating an envelope, use a single call to Envelopes:create or a corresponding SDK method rather than creating a draft envelope, then creating objects within the envelope via additional API calls, and then making an API call to send it.

• Your application should not create unused or unnecessary objects within the Docusign system. For example, draft envelope objects should not be created unless they will be sent.

• Download multiple objects with a single API call, when possible. For example, use the include query parameter for a call to Envelopes:listStatusChanges or a corresponding SDK method instead of making additional API calls for subsidiary objects.

• Rather than repeatedly polling to track your envelope status, use Docusign Connect and a listener to subscribe to receive updates. When the envelope status changes, Docusign Connect will send your listener a message letting you know and enabling your integration to respond immediately.

  Alternatively, you can improve polling efficiency by:

  • Decreasing the frequency that you poll for envelope status
  • Making sure that you don’t check status for envelopes that are already complete

Your integration is making an excessive number of requests to get envelope status. This reflects calls to the eSignature REST API Envelopes:get endpoint and corresponding SDK methods, which retrieve the status of an envelope.

Recommendations

• As a best practice, try to make fewer API calls per envelope. This includes envelope creation, any updates, and tracking.

• Instead of making separate calls to Envelopes:get to retrieve the status of multiple envelopes, you can make a single call to Envelopes:listStatusChanges or a corresponding SDK method that returns statuses for all envelopes that match filters you specify.

• Rather than repeatedly polling to track envelope status, use Docusign Connect and a listener to subscribe to receive updates. When an envelope status changes, Docusign Connect will send your listener a message letting you know and enabling your integration to respond immediately.

  Alternatively, you can improve polling efficiency by:

  • Decreasing the frequency at which you poll for envelope status
  • Making sure that you don’t check status for envelopes that are already complete

Your integration is making an excessive number of requests to get the status of envelope recipients. This includes calls to the eSignature REST API EnvelopeRecipients:list endpoint and corresponding SDK methods, which retrieve the status of all envelope recipients and identify the current recipient in the routing list.

Recommendations

• As a best practice, try to make fewer API calls per envelope. This includes envelope creation, any updates, and tracking.

• Rather than repeatedly polling to track recipient status, use Docusign Connect or Recipient Connect and a listener to subscribe to receive updates. When a recipient status changes, Docusign or Recipient Connect will send your listener a message letting you know and enabling your integration to respond immediately.

  Alternatively, you can improve polling efficiency by:

  • Decreasing the frequency at which you poll for recipient status
  • Making sure that you don’t check status for recipients who have completed their envelopes

This measures all eSignature REST API calls from your integration that reference the ID of an envelope that does not exist. Calls to nonexistent envelope IDs can occur after a failed call to Envelopes:create or a corresponding SDK method if the integration makes subsequent requests for that envelope.

Recommendations

• Include logic in the integration to handle a failed request to Envelopes:create or a corresponding SDK method, and ensure that no subsequent calls specify that envelope ID.
• For any request that receives an ENVELOPE_DOES_NOT_EXIST error code in the response, ensure that no further calls include that envelope ID.

Your integration is making an excessive number of API requests per envelope. This includes requests to create, update, and track an envelope. Reduce the number of calls made per envelope to increase your efficiency score.

Recommendations

As a best practice, try to make fewer API calls per envelope. This includes envelope creation, any updates, and tracking. You can streamline your envelope process by:

• When creating an envelope, use a single call to Envelopes:create or a corresponding SDK method rather than creating a draft envelope, then creating objects within the envelope via additional API calls, and then making an API call to send it.

• Your application should not create unused or unnecessary objects within the Docusign system. For example, draft envelope objects should not be created unless they will be sent.

• Download multiple objects with a single API call, when possible. For example, use the include query parameter for a call to Envelopes:listStatusChanges or a corresponding SDK method instead of making additional API calls for subsidiary objects.

• Rather than repeatedly polling to track your envelope status, use Docusign Connect and a listener to subscribe to receive updates. When the envelope status changes, Docusign Connect will send your listener a message letting you know and enabling your integration to respond immediately.

  Alternatively, you can improve polling efficiency by:

  • Decreasing the frequency that you poll for envelope status
  • Making sure that you don’t check status for envelopes that are already complete

Your integration did not make enough calls in the past seven days for Docusign to analyze its efficiency. In this case, Docusign sets the efficiency score to zero.

Recommendations

Increase the number of calls that the integration makes. When call volume over the previous seven days reaches a level that allows Docusign to analyze its efficiency, this factor will no longer appear in the Negative Efficiency Factors list for the integration.