Skip to main content

Quickstart

Get started with the Legalesign eSignature API in 5 minutes.

In this tutorial you will create an account and get an API key, make a GET query to confirm your credentials are working (and to get your team ID). Then you'll send an HTML document to be signed, download the signed version, and finally upload and send a PDF document.

Create your account

Create an account at legalesign.com sign up.

In the set up process you'll create a new organisation with one team. Select the option to start an API integration.

Teams are the main building blocks of Legalesign. All document processing occurs in a team. You'll identify a team in most of your API calls.

info

A 'team' or a 'group' are the same thing. In the web app we talk about 'teams', but in the API definition this is called a group.

Contact support to request an Api Key. Tell us your use-case, experience in API development, and some details so we can confirm you are real (e.g. details of where you work).

API settings

Once you have a key, go to API settings. This will contain your credentials and other API settings. Take a moment to review this section:

Sandbox

You'll see a badge to indicate you are in sandbox mode. Sandbox limits the signer emails where you can send test documents. You'll see a form where you can add up to 5 test emails.

When your integration is ready, read about how move to production mode.

tip

Create a second team. Use your first team for ongoing dev and other teams for prod. Tell support the name of your dev team to exclude it from billing.

API key

You'll see the details of your API key. Put the key into your Authorization header with this format

ApiKey username:secret

Webhooks & Logs

You'll see where you can add and remove webhooks, and link out to the API logging microsite. Click the tutorial links to learn more.

A successful GET request

Start with a simple GET request to confirm your auth is formatted properly. Replace username and secret.

Your root url is always: https://eu-api.legalesign.com/

We've used curl in the examples below, but python, js and go are given in the docs.


curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X POST https://eu-api.legalesign.com/api/v1/group/

See this call in detail, along with ready-made Python, Go and JS at GET group API reference. You can also use the OpenAPI3 schema to get an SDK in any language. We recommend however using your default language https library - the calls are all straightforward - as you'll see below.

When you run the call above, you'll see your groups in a JSON format. Success. 👏

In that data you'll see the resource uri for your group. It looks like /api/v1/group/:groupId/. Make a note of this, you'll want it for almost everything.

tip

A resource uri will always be formatted the same way. For a PDF it would be '/api/v1/templatepdf/:pdfId/', for a sent-document it will be '/api/v1/document/:documentId/'. Notice how all the URIs end with a slash. That's also true of the URLs for your API calls, always end them with a slash.

If the GET request failed, the most likely reasons are that your ApiKey is incorrectly formatted (you need it to start with the text 'ApiKey' and note the colon between username and secret), or the Content-Type header is missing, or you are missing an end slash. See also: troubleshooting.

Send a document for signature

Now you'll send a document to get signed. The main event.

To keep it simple we'll use HTML for this example. But we'll send a PDF as the next step. HTML is an easy way to start, you only need 1 api call. HTML gets converted into PDF after signing.

Send a document

For this we'll need some HTML and the email of a signer. Remember, you'll need to use the email of someone in your sandbox 'approved' emails.


curl -H "Authorization: [username]:[secret]" -H "Content-Type: application/json" -X POST --data '{ "group": "/api/v1/group/[:groupId]/", "name": "Name of doc", "text": "<h1>Non disclosure agreement</h1><p>terms as follows.. <span class=\"field\" data-optional=\"false\" data-name=\"Please add your ...\" data-idx=\"0\" data-signee=\"1\" data-type=\"signature\" data-options=\"\"> ....... </span></p>", "signers": [{"firstname": "Joe", "lastname": "Bloggs", "email": "[your@email.com]", "order": 0 }], "do_email": "true" }' https://eu-api.legalesign.com/api/v1/document/

Find and replace all the square-brackets with your details. Give it a try. API reference to send a document.

Notice the "text" attribute contains the HTML. As you can see, there are span fields with special attributes that tell Legalesign where you want people to sign. You can add form fields too, but lets keep it simple and get a signature for one signer.

Later, you'll replace 'text' with 'templatepdf' to send a PDF.

A successful call will return status code 201. ✨

Get the new sent document id

The important bit is the location header of the response you just received - this contains your documentId. You'll want to save that somewhere.

The location header will look like /api/v1/status/:documentId/.

You can make a GET query to that URI for a short (and fast to query) set of document attributes. For a GET request for everything query /api/v1/document/:documentId/.

info

The BODY of the response often contains error information if a request is unsuccessful. If you do not get a 201 status, check the BODY for explanatory text. See also troubleshooting.

Learn more about the Send Document API call.

Download the signed PDF

We recommend triggering a signed PDF download by using the webhook that notifies you when a document is signed.

The webhook will contain the documentId. Use it to make a PDF download request like so:

curl -H "Authorization: [username]:[secret]"  -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

PDF download API Reference.

The PDF binary is in the body of the response. The curl '-o' command puts the BODY of the response straight into a file. That's your PDF saved. Most REST or HTTP libraries treat HTTP response objects as if they were files, so typically you can simply save your response object like a normal file.

tip

Quick tip for testing out webhooks: use ngrok. Learn more about webhooks.

Send a PDF for signature(s)

You have sent and downloaded a document successfully, but what about PDFs.

Unless you already pre-prepared your PDFs via the web app (in which case skip to the next paragraph), PDFs first need to be uploaded and their ID saved.

Upload a PDF

For this call, you need to convert your PDF binary into base64 encoded text.

This is some general purpose pseudocode that should make sense in a broad way. Adapt to your preferred language as appropriate:

$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'ApiKey username:secret',
'Content-Type': 'application/json'
)
response = httplibrary.post('https://eu-api.legalesign.com/api/v1/templatepdf/', jsonEncode($data), $headers)
assert response.status == 201

pdfId = response.headers['location']

PDF upload API reference.

As is usual with a POST request, a successful response will return a '201' status and the new ID will be in the 'location' header of the response.

assert response.status == 201
pdfId = response.headers['location']

Your pdf resource URI will look like /api/v1/templatepdf/:pdfId/.

Before you start coding this part, read on to learn about PDF fields.

Send the new PDF

Go back to the code used to send an HTML document. Remove the 'text' attribute (which contains HTML) and replace it with 'templatepdf', plus your new pdf URI as its value.

That's it, you will send out your PDF to be signed.

What about PDF fields?

You may have noticed we missed something. How does Legalesign know where the person needs to sign on the PDF? The answer is our PDF was pre-prepared, we put a Legalesign text tag in the PDF and set 'process_tags' to true in the upload call.

Text tags are specially formatted text to put in a PDF. Legalesign will parse them and replace those tags with signature and form fields. For one signer all you need to do is add: <<t=signature>>. Legalesign will identify it and locate the signature there. Learn about text tags in PDFs.

Click here to download the pre-prepared PDF. Use it for your own first PDF upload.

Text tags have a learning curve and need trial and error, use the web app to test out tags, and contact support@legalesign.com for assistance and examples.

There are two alternatives, you may want to start with option i) for this tutorial:

i) easiest/quickest version - set up your PDF using the Legalesign web app. After you upload a PDF you'll go to the editor interface where you can drag and drop form fields. Drag and drop a signature, then note the PDF Id in the web address. The web address is formatted like so https://app1.legalesign.com/:groupId/pdf/edit/:pdfId/, get the pdfId and you have your PDF resource uri - /api/v1/templatepdf/:pdfId/.

ii) use x/y coordinates to define where you want signature and form fields. The simplest way to get started with this is to set up a PDF in the web app and add form fields, then API query for those fields (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/). This query will give you a JSON object of how form fields should be prepared. Just customise and use the Create PDF Field endpoint - which is the same endpiont but with a POST method (adjusting pdfId accordingly).

Happy coding!

You have done a successful query for your group(s). Sent out a document for signing using HTML and a PDF, and downloaded a signed doc. 🥳

Happy coding! We're here to help, contact support@legalesign.com for any assistance.