Skip to main content


Get started with the Legalesign eSignature API in 5 minutes.

In this tutorial you will:

  • create an account and get an API key (see help article Get verified for API access),
  • make a GET query to confirm your credentials are working (and get your team ID),
  • send a HTML document to be signed then download it, and
  • upload a PDF document and send that to be signed.

The full API reference is at Rest API v1 in the navigation at the top of the page. You can test out calls using your API key, and copy ready-made python, php, ruby, csharp, nodejs, right from within the documentation.

Below is a quick guide to the docs interactive feature, including how to make a GET query to confirm your credentials are working and get your team ID.

The API is highly versatile, from simple PDF send & sign, to complex witnessing and approvals, with multi-user management. If you are integrating eSignature for multiple end-customers see integration.

Create your account

Create an account at sign up. During the signup process follow the option to start an API integration.

Teams are the building blocks of Legalesign. All document processing occurs in a team. You will refer to your team in most API calls - we will get the API reference below.


A 'team' or a 'group' are the same thing. In the web app we talk about 'teams', but in the API schema it's 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. You will see your credentials and other API settings.

Take a moment to review this section:


A badge shows if you are in sandbox or production mode.

Sandbox limits where you can send your documents. You'll see a form to add up to 5 approved emails - add a few now.

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


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 following 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:

We've used curl in the examples below, but examples in python, nodejs, go, php and csharp are given in the REST documentation.

curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET

See this call in details at GET group API reference.

The REST API reference guide is a mini SDK generator and produces code in several languages. You can also use the OpenAPI3 schema to generate SDKs. We recommend trying first with the code snippets from the documentation - - the calls are all straightforward.

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

Within 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.


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: ApiKey [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": "[]", "order": 0 }], "do_email": "true" }'

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/.


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: ApiKey [username]:[secret]"  -o download.pdf -X GET

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.


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 ='', 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 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, 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 for any assistance.