HelloSign API Documentation

Short animation demonstrating the try it console

The HelloSign API offers a reliable, flexible set of eSignature tools that can be used to power digital agreements and turn slow, outdated business processes into a competitive advantage. With a broad range of highly-configurable features, the HelloSign API empowers you to build secure signing experiences and document workflows that delight your users.

This documentation contains information and resources to help you build with the HelloSign API. Here's some of what you'll find here:

  • API Reference - comprehensive technical information and code examples for the entire HelloSign API. Includes a Try it console to explore and test endpoints by sending API calls directly from the docs.
  • Guides / Walkthroughs -- in-depth information and tutorials about features, concepts, and use cases.
  • Libraries -- links to official HelloSign SDKs.
Work in Progress

This documentation is constantly evolving and improving. Changes to layout or content may occur. We highly recommend using the search feature if you need help finding something.



Testing the HelloSign API

You can fully test every endpoint and almost feature in the HelloSign API (even from a free account) by setting test_mode to true on your API requests. There are a few key behaviors to be aware of:
  • Signature requests created in test_mode are not legally binding and documents are watermarked as such.
  • Signature requests submitted in test_mode will be visible in the HelloSign accounts of requester and signers. Please consider the e-mail addresses you use when testing.
  • You can add custom branding that will be applied to calls sent with test_mode. However, production requests will ignore those settings unless you're subscribed to a Standard or Premium plan.


How we charge

Sending production (legally-binding) signature requests requires a paid API plan. The API will return a status code of 402 if such requests are made without a proper plan. We understand that you may want to test the API before paying for it. Some API endpoints are restricted to paid plans, but can still be used without signing up for a paid plan by using our test mode. See the Testing section above.

Endpoints by subscription plan

The endpoints below are organized by the subscription plan required to use them.

Required PlanNotes
Freebuild with all endpoints using test_mode
EssentialsAccess to signature request endpoints. Can use templates created on hellosign website.
signature_request/send
signature_request/send_with_template
StandardAccess to bulk send, embedded signing, and embedded requesting endpoints.
signature_request/bulk_send_with_template
signature_request/create_embedded
signature_request/create_embedded_with_template
signature_request/bulk_create_embedded_with_template
unclaimed_draft/create
unclaimed_draft/create_embedded
unclaimed_draft/create_embedded_with_template
unclaimed_draft/edit_and_resend/{signature_request_id}
PremiumAccess to embedded template endpoints. Note that this plan comes with lots of advanced signer fields and signing tools.
template/create_embedded_draft
template/update_files/{template_id}


Rate Limits

To maximize stability for everyone, the HelloSign API enforces rate limits on the number of API calls over a specific period of time. Exceeding the rate limits in this section may result in an error with a status code of 429.

By default, you can make up to 100 requests per minute for standard API requests, and 25 requests per minute for higher tier API requests. In test mode, you can do 10 requests per minute. Exceptions can be made for customers with higher volumes. Please contact us for more information.

Higher tier API endpoints:

Rate limit information is returned in the HTTP headers of any API request:

$ curl -i -u '5b2a72b84c3037711d0578e9f93589a38661f093aa4ea48bd8324c16203364eb' https://api.hellosign.com/account 
HTTP/1.1 200 OK
...
X-Ratelimit-Limit: 100
X-Ratelimit-Limit-Remaining: 99
X-Ratelimit-Reset: 1430170900
...

Use these headers to understand how your requests are being limited.

Header NameDescription
X-Ratelimit-LimitThe maximum number of requests per hour that you can make.
X-Ratelimit-Limit-RemainingThe number of requests remaining in the current rate limit window.
X-Ratelimit-ResetThe Unix time at which the rate limit will reset to its maximum.

If your application triggers this rate limit, you'll receive the following response:

HTTP/1.1 429 Too Many Requests 
Connection: close
Content-Type: application/json
Copy
Copied
{
    "error": {
        "error_msg": "Too many requests. System limits for this type of request are 2000 per hour.",
        "error_name": "exceeded_rate"
    }
}

Use the response headers and message above to limit your requests to the HelloSign API. If you're exceeding your rate limit frequently, you will receive an email notifying you of the overage. It is important to address these notifications, as excessive rate limit abuse will be addressed by blocking the offending account until the situation is resolved. Please contact us if you require a rate limit increase.



API Dashboard



Quickstart

Ready to take your first steps with the HelloSign API? We recommend using the Try it console to send API calls directly from the endpoint you'd like to explore. We do offer a Quickstart that was migrated from our previous documentation, but it takes a little more work to send API calls that way.

Work in Progress

HelloSign's API Engineering team is actively investing in developer experience. This section will be updated to reflect new resources as they're available.