Quickstart Tutorial
In this tutorial you will do the major parts of an eSignature integration, using both HTML and PDF document systems.
Legalesign API is scalable, versatile, and production tested in our customers systems for many years. You can use it for a simple one signer document, or send documents for witnessing or approvals, optimised for batches, with forms and more. You can integrate for one purpose or embed it within your software for your customers - see integrations.
5 steps to get up and running:
- Create an account + API Key (see Get verified for API access).
- Confirm credentials work and get your team ID.
- Send a HTML document to be signed.
- Upload and send a PDF document to be signed.
- Download a signed document.
Legalesign REST API is easy to use. The technical reference includes a code editor. You can make requests right from the technical reference with your api key, but otherwise just copy and paste straight into your code.
Figure 1: The REST API Code Editor.
Need an SDK? The quickest way to code your integration is to upload this OpenAPI specification to your AI tooling - and to read this documentation. If an SDK is preferred, it can be generated directly from the OpenAPI specification, or you may wish to review these in C# and JavaScript. But coding directly to the API with your AI ensures full feature coverage, reduces abstraction overhead, and avoids introducing additional code dependencies.
1. Create an account
Go to legalesign sign up. Use a normal email to create the account (do not use Google), federated identities like Google won't work for the API.
You will be asked to create a team. Teams are the building blocks of Legalesign. All document processing occurs in a team. You need to refer to your team in most API calls.
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 for 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 are verified go to the API Dashboard. Generate your API credentials in the Config section.
Take a moment to review this section:
Sandbox
An alert shows whether 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 dev and other team(s) 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 in the following format:
ApiKey username:secret
Add that to the Authorization header of your requests.
Webhooks & Logs
Add webhooks (your listeners for Legalesign events), and review your logs.
2. A successful GET request
The root url is always: https://eu-api.legalesign.com/
Start with a GET request to confirm your credentials are working. Replace username and secret values in the code below.
Curl is used in the examples, but go to the documentation (link below the examples) to get snippets in different languages.
curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/
API documentation: GET group API reference.
When you execute the query above, you'll see your groups returned in JSON. Success. 👏
The response data contains the 'resource uri' for your group and looks like /api/v1/group/:groupId/. Make a note of this, you'll need it for most API calls.
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 then check that:
- your ApiKey is correctly formatted (starts with 'ApiKey),
- you have a Content-Type header for application/json, and
- your url ends with a slash.
See also troubleshooting.
3. Send a document for signature
Now send a document to get signed.
For simplicity we'll use HTML for the first send. But we'll upload and send a PDF in the next example. HTML is an easy way to start, you only need 1 api call. HTML gets converted into PDF after signing.
Send a document
We'll need some HTML and the email of a signer. Remember to use an email 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": "[your@email.com]", "order": 0 }], "do_email": "true" }' https://eu-api.legalesign.com/api/v1/document/
Update all the square-brackets. API reference to send a document.
When you visit the reference documentation for sending a document take a quick look through all the possible attributes. You'll see many that will help with the practicalities of an integration - tags for your own references and IDs (which come back to you in webhooks), a redirect for signers, set custom text in the pdf, and more.
Notice the "text" attribute contains the HTML. SPAN fields with special attributes tell Legalesign where you want people to sign. You can add form fields too, but in this example we get a signature for one signer.
Later, you use the same endpoint to send a PDF but replace the 'text' attribute with 'templatepdf'.
A successful call will return status code 201. ✨
Get the new sent document id
The important part of the response is the location header. This contains your new document id.
Tag documents with your own references to make it easier to sync them to your own database.
The location header will look like /api/v1/status/:documentId/.
The 'status' URI returns a short (and fast to query) set of document attributes.
To request everything from a document use /api/v1/document/:documentId/.
If a request is unsuccessful the BODY of the response usually contains error information. If you do not get a success status, check the BODY for explanatory text. See also troubleshooting.
Learn more about the Send Document API call.
Download the signed document
With the document ID you received earlier, make a PDF download request like so:
curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/
The PDF binary is in the body of the response. The curl '-o' command puts the BODY of the response straight into a file.
Many REST or HTTP libraries treat HTTP response objects as if they were files in which case simply save your response object like a normal file.
Use webhooks to get notified of a signing event and then download the document. See webhooks.
4. Send a PDF for signature(s)
In the last section you sent a HTML-based document, now 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
Click here to download a sample text-tagged PDF, more about PDF form fields to follow.
For this call, convert your PDF into a base64 encoded string. This is not properly done within the documentation code generator. Instead copy this pseudocode and your friendly AI will convert it to your preferred language:
$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']
As usual, a successful POST response will return '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/.
Send the new PDF
Go back to the earlier code you used to send an HTML document (the POST to /api/v1/document/). Replace the 'text' attribute (and its html) with 'templatepdf' and your new pdf resource URI.
Issue the request again (now with the 'templatepdf' attribute replacing 'text') and that's it, you sent out your PDF for signing.
Before you start coding, however, read on to learn more about PDF fields.
What about PDF fields?
How does Legalesign know where the person needs to sign on the PDF? The answer is that our PDF was pre-prepared with tags: we put a Legalesign text tag within the PDF and set 'process_tags' to true in the PDF upload request.
Click here to download a sample text-tagged PDF.
Text tags are specially formatted text to put in a PDF. Legalesign will parse the text in your file, replacing the 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.
Text tags have a learning curve and need trial and error. Other methods are set out below, but you get the full capability of the Legalesign forms system with it. Use the web app to test out tags. Contact support for assistance and examples.
Here are four ways to set up fields:
1. 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 encoded ID in the web address. This will look something like 'dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk'.
Base64 decode this ID and you'll see it's a UUID prefixed with 'pdf'. The UUID-part (remove 'pdf') is your pdfID. Learn more about Legalesign IDs.
Your API PDF resource uri will be - /api/v1/templatepdf/:pdfId/.
Put that into the 'templatepdf' attribute of the send document call.
If you plan to send this PDF more than once, make sure 'Auto archive' is turned off. See how
2. Use x/y coordinates for fields.
The simplest way to get started with x/y coordinates is to set up a PDF in the web app and then API query for those fields (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).
The JSON object you get back is the exact same JSON schema you need to create fields too.
Use it as a template. Amend any values and POST it back to the same endpoint (adjusting the PDF ID as appropriate). Create PDF Field endpoint.
3. Create an embedded PDF edit page.
Redirect your users to it after upload and your users can drag and drop fields themselves - see documentation.
4. PDF Form Fields NEW!
If your PDF contains normal PDF Form Fields, Legalesign can import them automagically.
Happy coding!
In this tutorial you acquired API credentials, successfully queried for your group(s), sent out a document for signing using HTML and PDF, and downloaded a signed doc.
Happy coding! We're here to help, contact support for any assistance.