Make your first API call in a few steps
Using your interface
Using our website
Use your interface
Have users sign documents on your website. Embed documents directly on your website with just a few lines of codes.

The following steps will guide you through setting up a document that can be signed by your site users without ever having to leaving 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="//s3.amazonaws.com/cdn.hellofax.com/js/embedded.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.

Use our website
Have users sign documents on HelloSign.com. We notify the signer via email and collect their eSignature on HelloSign.

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.

Testing

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.

Restricted endpoints

The following API endpoints require a paid plan but are always accessible in test mode:

Templates

Need templates for testing? Contact apisupport@hellosign.com and we'll add 5 to your account.

Authentication

Our API primarily uses basic authentication to identify users when processing requests. Authentication data is securely encrypted using SSL.

Basic Authentication

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.

OAuth

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.

Permissions

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.

How we charge

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.

Rate limits

You can make up to 500 requests per hour (50 requests per hour in test mode).

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

$ curl -i -u 'your_api_key' https://api.hellosign.com/v3/account
HTTP/1.1 200 OK
...
X-Ratelimit-Limit: 500 
X-Ratelimit-Limit-Remaining: 499 
X-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-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 403 Forbidden
Connection: close
Content-Type: application/json

{
    "error": {
        "error_msg": "Too many api requests. System limits are 500 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 temporary rate limit increase.