HelloSign API Quickstart

Legacy Resource

This quickstart was migrated and may contain outdated examples. Once newer quickstart materials are published, it will be marked as deprecated.

This quickstart was migrated intact because it adds helpful context around non-embedded vs embedded workflows, which is a fundamental concept for the HelloSign API. Please make use of the knowledge here, but be aware that this resource may change in the near future.

Using Our Website -- Non-embedded Signing

In non-embedded signing flows, you send the signature request and HelloSign handles the rest. We notify the signer via email, they follow a link, and we collect their eSignature on a HelloSign-owned web page.

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 free account if you don't already have one and retrieve your API key from the settings page.
  2. Send your first signature request.
curlphpjavapythonrubynodejsC#
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/send' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -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]=1fe4c21a@mailinator.com' \
    -F 'signers[0][name]=Me' \
    -F 'file[0]=@NDA.pdf' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$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);
Copy
Copied
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_CREATE_API_KEY_FIRST");
SignatureRequest newRequest = client.sendSignatureRequest(request);
Copy
Copied
from hellosign_sdk import HSClient
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
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': '1fe4c21a@mailinator.com', 'name': 'Me' }],
    files=['NDA.pdf']
)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
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 => '1fe4c21a@mailinator.com',
            :name => 'Me'
        }
    ],
    :files => ['NDA.pdf']
)
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

const opts = {
  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.',
  signers: [
    {
      email_address: '1fe4c21a@mailinator.com',
      name: 'Me'
    }
  ],
  files: ['NDA.pdf']
};

hellosign.signatureRequest.send(opts).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = new SignatureRequest();
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("1fe4c21a@mailinator.com", "Me");
request.AddFile("C:\Users\Me\My Documents\NDA.pdf");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
  1. Check the status of your signature request (use the signature_request_id field returned in step #2).
curlphpjavapythonrubynodejsC#
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/SIGNATURE_REQUEST_ID' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:'
Copy
Copied
$signature_request = $client->getSignatureRequest('SIGNATURE_REQUEST_ID');
Copy
Copied
SignatureRequest newRequest = client.getSignatureRequest("SIGNATURE_REQUEST_ID");
Copy
Copied
client.get_signature_request('SIGNATURE_REQUEST_ID')
Copy
Copied
client.get_signature_request :signature_request_id => 'SIGNATURE_REQUEST_ID'
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.signatureRequest.get(signatureRequestId).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var response = client.GetSignatureRequest("SIGNATURE_REQUEST_ID");
  1. Go to your inbox and follow the instuctions to sign the signature request. After doing so, you can redo step #3 and see the difference.
  2. Download the signed document.
curlphpjavapythonrubynodejsC#
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/files/SIGNATURE_REQUEST_ID' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -o mySignedDocument.pdf
Copy
Copied
$client->getFiles('SIGNATURE_REQUEST_ID', $dest_file_path, HelloSign\SignatureRequest::FILE_TYPE_PDF);
Copy
Copied
File pdf = client.getFiles("SIGNATURE_REQUEST_ID");
Copy
Copied
client.get_signature_request_file(
    signature_request_id='SIGNATURE_REQUEST_ID',
    filename='mySignedDocument.pdf'
)
Copy
Copied
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
Copy
Copied
const fs = require('fs');
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.signatureRequest.download(signatureRequestId, (err, res) => {
  const file = fs.createWriteStream('file.pdf');

  res.pipe(file);

  file.on('finish', () => {
    file.close();
  });
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
client.DownloadSignatureRequestFiles("SIGNATURE_REQUEST_ID", "mySignedDocument.pdf");

Using Your Interface -- Embedded Signing

In embedded signing flows, HelloSign is providing the eSign technology, but you're embedding the signing experience into your app or web page. In this model, all emails from HelloSign are muted and the developer is responsible for managing their user notifications directly. HelloSign Events can help with that.

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 free account 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 the backend
curlphpjavapythonrubynodejsC#
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/create_embedded' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'subject=My First embedded signature request' \
    -F 'message=Awesome, right?' \
    -F 'signers[0][email_address]=1fe4c21a@mailinator.com' \
    -F 'signers[0][name]=Me' \
    -F 'file[0]=@NDA.pdf' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$request->setSubject('My First embedded signature request');
$request->setMessage('Awesome, right?');
$request->addSigner('1fe4c21a@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);
Copy
Copied
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_CREATE_API_KEY_FIRST");
SignatureRequest newRequest = (SignatureRequest) client.createEmbeddedRequest(embedReq);
Copy
Copied
from hellosign_sdk import HSClient
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
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': '1fe4c21a@mailinator.com', 'name': 'Me' }],
    files=['NDA.pdf']
)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
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 => '1fe4c21a@mailinator.com',
            :name => 'Me'
        }
    ],
    :files => ['NDA.pdf']
)
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

const opts = {
  test_mode: 1,
  clientId: 'b6b8e7deaf8f0b95c029dca049356d4a2cf9710a',
  subject: 'The NDA we talked about',
  message: 'Please sign this NDA and then we can discuss more.',
  signers: [
    {
      email_address: 'alice@example.com',
      name: 'Alice'
    }
  ],
  files: ['NDA.pdf']
};

hellosign.signatureRequest.createEmbedded(opts).then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = new SignatureRequest();
request.Subject = "My First embedded signature request";
request.Message = "Awesome, right?";
request.AddSigner("1fe4c21a@mailinator.com", "Me");
request.AddFile("C:\Users\Me\My Documents\NDA.pdf");
request.TestMode = true;
var response = client.CreateEmbeddedSignatureRequest(request, "YOUR_CLIENT_ID");
  1. Retrieve the embedded signature URL that will be needed by the frontend.
curlphpjavapythonrubynodejsC#
Copy
Copied
curl 'https://api.hellosign.com/v3/embedded/sign_url/SIGNATURE_ID' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:'
Copy
Copied
$response = $client->getEmbeddedSignUrl('SIGNATURE_ID');
Copy
Copied
EmbeddedResponse response = client.getEmbeddedSignUrl("SIGNATURE_ID");
String url = response.getSignUrl();
Copy
Copied
obj = client.get_embedded_object('SIGNATURE_ID')
sign_url = obj.sign_url
Copy
Copied
client.get_embedded_sign_url :signature_id => 'SIGNATURE_ID'
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.signatureRequest.createEmbedded(opts).then((res) => {
  const signature = res.signature_request.signatures[0];
  const signatureId = signature.signature_id;

  return hellosign.embedded.getSignUrl(signatureId);
}).then((res) => {
  console.log('The sign url: ' + res.embedded.sign_url);
}).catch((err) => {
  // handle error
});
Copy
Copied
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var response = client.GetSignUrl("SIGNATURE_ID");
  1. Install hellosign-embedded from npm.
Copy
Copied
npm install hellosign-embedded
  1. Create a test app and retrieve the associated client id.
In your frontend app, import the hellosign-embedded module, instantiate a new client with your API client ID, then call open() with the signUrl from the previous step.
Copy
Copied
import HelloSign from 'hellosign-embedded';

const client = new HelloSign();

client.open(signUrl, {
  clientId: 'Your API client ID'
});
  1. Go to your web page and watch the magic happen.