The following steps will guide you through setting up a document that can be signed by your users without ever having to leave your site.
1. Create a if you don't already have one and retrieve your API key from the settings page.
2. Create a test app and retrieve the associated client id.
3. Create a signature request from your back end.
4. Retrieve the embedded signature url that will be needed on the front end.
5. Insert the following Javascript code on your page, with SIGN_URL being from the response given by the previous back end call.
<script type="text/javascript" src="https://s3.amazonaws.com/cdn.hellosign.com/public/js/hellosign-embedded.LATEST.min.js"></script>
<script type="text/javascript">
HelloSign.init("{CLIENT_ID}");
HelloSign.open({
url: "SIGN_URL",
allowCancel: true,
messageListener: function(eventData) {
alert("HelloSign event received");
}
});
</script>6. Go to your web page and watch the magic happen.
The following steps will guide you through the process of using the HelloSign API to send a signature request, track its status, and retrieve the document once it's been signed.
1. Create a if you don't already have one and retrieve your API key from the settings page.
2. Send your first signature request.
3. Check the status of your signature request (use the signature_request_id field returned in step #2).
4. Go to your mailinator inbox and follow the instuctions to sign the signature request. After doing so, you can redo step #3 and see the difference.
5. Download the signed document.
It is possible to access the API in test mode using the boolean parameter "test_mode". Signature requests created in test mode are not legally binding and are watermarked as such.
The following API endpoints require a paid plan but are always accessible in test mode:
Use HelloSign's API Dashboard to see your API requests and responses, view the status of your signature requests, and inspect your callbacks for easy troubleshooting and debugging.
This video takes you through the dashboard:
Our API primarily uses basic authentication to identify users when processing requests. Authentication data is securely encrypted using SSL.
Use your API key as the user name and leave the password empty. Your API key can be found on the settings page.
Alternatively, you can use your email address and password.
We also support OAuth (2.0 only) as a way of authenticating. For more details on this topic, take a look at our OAuth guide.
If you have a HelloSign team, you must be a designated admin or developer to access the API. You can view and set team roles on the team page.
The creation of live signature requests is not free and requires a paid API plan. The API will return HTTP 402 if such requests are made without a proper plan.
We understand that you may want to test the API before paying for it. The only API endpoints that are restricted to paid plans are the ones used to send signature requests. However, they can still be used without signing up for a paid plan by using our test mode. See the Testing section above.
By default, you can make up to 2000 requests per hour for standard API requests, and 500 requests per hour for higher tier API requests. In test mode, you can do 50 requests per hour. 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 'SIGN_IN_AND_CREATE_API_KEY_FIRST' https://api.hellosign.com/v3/account HTTP/1.1 200 OK ... X-Ratelimit-Limit: 2000X-Ratelimit-Limit-Remaining: 1999X-Ratelimit-Reset: 1430170900 ...
Use these headers to understand how your requests are being limited.
| Header Name | Description |
|---|---|
| X-Ratelimit-Limit | The maximum number of requests per hour that you can make. |
| X-Ratelimit-Limit-Remaining | The number of requests remaining in the current rate limit window. |
| X-Ratelimit-Reset | The 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
{
"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.