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.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/signature_request/create_embedded' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:' \
-F 'client_id=YOUR_CLIENT_ID' \
-F 'subject=My First embedded signature request' \
-F 'message=Awesome, right?' \
-F 'signers[0][email_address]=319ead5b@mailinator.com' \
-F 'signers[0][name]=Me' \
-F 'file[0]=@NDA.pdf' \
-F 'test_mode=1'
                
$client = new HelloSign\Client('SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setSubject('My First embedded signature request');
$request->setMessage('Awesome, right?');
$request->addSigner('319ead5b@mailinator.com', 'Me';
$request->addFile($path_to_nda_pdf);

$client_id = 'YOUR_CLIENT_ID';
$embedded_request = new HelloSign\EmbeddedSignatureRequest($request, $client_id);
$response = $client->createEmbeddedSignatureRequest($embedded_request);
                
SignatureRequest request = new SignatureRequest();
request.setSubject("My First embedded signature request");
request.setMessage("Awesome, right?");
request.addSigner("jack@example.com", "Jack");
request.addFile(new File("NDA.pdf"));
request.setTestMode(true);

EmbeddedRequest embedReq = new EmbeddedRequest("YOUR_CLIENT_ID", request);

HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE");
SignatureRequest newRequest = client.createEmbeddedRequest(embedReq);
                
from hellosign_sdk import HSClient
client = HSClient(api_key='SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE')
client.send_signature_request_embedded(
    test_mode=True,
    client_id='YOUR_CLIENT_ID,
    subject="My First embedded signature request",
    message="Awesome, right?",
    signers=[{ 'email_address': '319ead5b@mailinator.com', 'name': 'Me' }],
    files=['NDA.pdf']
)
                
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'
client.create_embedded_signature_request(
:test_mode => 1,
:client_id => 'YOUR_CLIENT_ID',
:subject => 'My First embedded signature request',
:message => 'Awesome, right?',
:signers => [
{
:email_address => '319ead5b@mailinator.com',
:name => 'Me'
}
],
:files => ['NDA.pdf']
)
                
var hellosign = require('./hellosign.js')({key: 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'});
                    hellosign.signatureRequest.createEmbedded({
                    test_mode : 1,
                    clientId : 'YOUR_clientId',
                    subject : 'My First embedded signature request',
                    message : 'Awesome, right?',
                    signers : [
                    {
                    email_address : '319ead5b@mailinator.com',
                    name : 'Me'
                    }
                    ],
                    files : ['NDA.pdf']
                    },function(err, success){})
                

4. Retrieve the embedded signature url that will be needed on the front end.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/embedded/sign_url/SIGNATURE_ID' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:'
                
$response = $client->getEmbeddedSignUrl('SIGNATURE_ID');
EmbeddedResponse response = client.getEmbeddedSignUrl("SIGNATURE_ID");
String url = response.getSignUrl();
                
obj = client.get_embedded_object('SIGNATURE_ID')
sign_url = obj.sign_url
                
client.get_embedded_sign_url :signature_id => 'SIGNATURE_ID'
var hellosign = require('./hellosign.js')({key: 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'});
                    hellosign.getEmbeddedSignUrl('SIGNATURE_ID',function(err, success){});

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.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/signature_request/send' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:' \
-F 'title=NDA with Acme Co.' \
-F 'subject=The NDA we talked about' \
-F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
-F 'signers[0][email_address]=319ead5b@mailinator.com' \
-F 'signers[0][name]=Me' \
-F 'file[0]=@NDA.pdf' \
-F 'test_mode=1'
                
$client = new HelloSign\Client('SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setTitle('NDA with Acme Co.');
$request->setSubject('The NDA we talked about');
$request->setMessage('Please sign this NDA and then we can discuss more. Let me know if you have any questions.');
$request->addSigner('jack@example.com', 'Jack');
$request->addFile($path_to_nda_pdf);
$response = $client->sendSignatureRequest($request);
                
SignatureRequest request = new SignatureRequest();
request.setTitle("NDA with Acme Co.");
request.setSubject("The NDA we talked about");
request.setMessage("Please sign this NDA and then we can discuss more. Let me know if you have any questions.");
request.addSigner("jack@example.com", "Jack");
request.addFile(new File("NDA.pdf"));
request.setTestMode(true);

HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE");
SignatureRequest newRequest = client.sendSignatureRequest(request);
                
from hellosign_sdk import HSClient
client = HSClient(api_key='SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE')
client.send_signature_request(
    test_mode=True,
    title="title=NDA with Acme Co.",
    subject="The NDA we talked about",
    message="Please sign this NDA and then we can discuss more. Let me know if you have any questions.",
    signers=[{ 'email_address': '319ead5b@mailinator.com', 'name': 'Me' }],
    files=['NDA.pdf']
)
                
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'
client.send_signature_request(
:test_mode => 1,
:title => 'NDA with Acme Co.',
:subject => 'The NDA we talked about',
:message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
questions.',
:signers => [
{
:email_address => '319ead5b@mailinator.com',
:name => 'Me'
}
],
:files => ['NDA.pdf']
)
                
var hellosign = require('./hellosign.js')({key: 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'});
                    hellosign.signatureRequest.send({
                    test_mode: 1,
                    title: 'NDA with Acme Co.',
                    subject: 'The NDA we talked about',
                    message: 'Please sign this NDA and then we can discuss more. Let me know if you have any
                    questions.',
                    signers: [
                    {
                    email_address: '319ead5b@mailinator.com',
                    name: 'Me'
                    }
                    ],
                    files: ['NDA.pdf']
                    },function(err, success){})
                

3. Check the status of your signature request (use the signature_request_id field returned in step #2).

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/signature_request/SIGNATURE_REQUEST_ID' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:'
                
$signature_request = $client->getSignatureRequest('SIGNATURE_REQUEST_ID');
SignatureRequest newRequest = client.getSignatureRequest("SIGNATURE_REQUEST_ID");
client.get_signature_request('SIGNATURE_REQUEST_ID')
client.get_signature_request :signature_request_id => 'SIGNATURE_REQUEST_ID'
hellosign.signatureRequest.get('SIGNATURE_REQUEST_ID', function(err, success));

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.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/signature_request/files/SIGNATURE_REQUEST_ID' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:' \
-o mySignedDocument.pdf
                
$client->getFiles('SIGNATURE_REQUEST_ID', $dest_file_path, SignatureRequest::FILE_TYPE_PDF);
                
File pdf = client.getFiles("SIGNATURE_REQUEST_ID");
client.get_signature_request_file(
    signature_request_id='SIGNATURE_REQUEST_ID',
    filename='mySignedDocument.pdf'
)
                
file_bin = client.signature_request_files :signature_request_id => 'SIGNATURE_REQUEST_ID', :file_type='pdf'
open("mySignedDocument.pdf", "wb") do |file|
file.write(file_bin)
end
                
hellosign.signatureRequest.download('SIGNATURE_REQUEST_ID', function(err, response){
                    var fs = require('fs');
                    var file = fs.createWriteStream("file.pdf");
                    response.pipe(file);
                    file.on('finish', function() {
                    file.close();
                    });
                    });
                
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.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/account' \
-u 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE:'
                
$client = new HelloSign\Client('SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE');
$account = $client->getAccount();
                
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE");
Account account = client.getAccount();
                
client = HSClient(api_key='SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE')
client.get_account_info()
                
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'
client.get_account
                
var hellosign = require('./hellosign.js')({key: 'SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE'});
                    hellosign.account.get({},function(err, success){});
                

Alternatively, you can use your email address and password.

curl
php
java
python
ruby
nodejs
curl 'https://api.hellosign.com/v3/account'
-u '{YOUR EMAIL ADDRESS}:{YOUR PASSWORD}'
                
$client = new HelloSign\Client('{YOUR EMAIL ADDRESS}','{YOUR PASSWORD}');
$account = $client->getAccount();
                
HelloSignClient client = new HelloSignClient("{YOUR EMAIL ADDRESS}", "{YOUR PASSWORD}");
Account account = client.getAccount();
                
client = HSClient(email_address="{YOUR EMAIL ADDRESS}", password="{YOUR PASSWORD}")
client.get_account_info()
                
client = HelloSign::Client.new :email_address => "{YOUR EMAIL ADDRESS}", :password => "{YOUR PASSWORD}"
client.get_account
                
var hellosign = require('./hellosign.js')({email_address: "{YOUR EMAIL ADDRESS}", password: "{YOUR PASSWORD}"});
                    hellosign.account.get({},function(err, success){});
                
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.

NOTE The current rate limits are 500 production-mode requests per hour, and 50 test-mode requests per hour.