Quickstart
Get started with the Legalesign eSignature API in 5 minutes.
In this article we:
- Create an account and get an API key (see help article Get verified for API access).
- Make a GET query to confirm our credentials are working (and get a team ID).
- Send a HTML document to be signed, then download it.
- Upload a PDF document and send that to be signed.
Full API documentation is linked from the top of the page - Rest v1 API.
The documentation has a mini code generator that outputs python, php, ruby, c#, node.js and go. You can also use the OpenAPI3 schema to generate SDKs. We recommend trying first with the code generator - the calls are all straightforward.
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.
1. Create an account
Go to legalesign sign up. Use a normal email to create the account. Federated identities like Google won't work for the API. During the signup process follow the option to start an API integration.
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 - the first step below is to get your team ID.
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).
In the meantime set up 2FA on your account in the web app, it's a requirement for API access.
API settings
Once you are verified go to API settings. 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.
(Learn more about the API dashboard).
2. A successful GET request
Your root url is always: https://eu-api.legalesign.com/
Start with a simple GET request to confirm your auth is formatted properly. Replace username and secret values in the code below.
Curl is used in the examples, but go to the endpoint's documentation to get snippets in python, nodejs, go, php or csharp.
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 run the call above, you'll see your groups in a JSON format. 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 either your ApiKey is incorrectly formatted or the Content-Type header is missing (content-type: application/json), or you are missing an end slash on the endpoint URL. See troubleshooting.
3. 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 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-bracketed values. API reference to send a document.
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, we replace the 'text' attribute with 'templatepdf' to send a PDF.
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.
Documents accepts tag attributes. These are included in webhooks. Use them for your own IDs and potentially avoid the need to save Legalesign IDs.
The location header will look like /api/v1/status/:documentId/.
A GET query to that 'status' URI returns a short (and fast to query) set of document attributes. For a GET request of everything 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 PDF
We recommend triggering a signed PDF download by using the webhook that notifies you when a document is signed.
With a document ID you can 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.
Quick tip for testing out webhooks: use ngrok. Learn more about webhooks.
4. 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 a base64 encoded string. This is not properly done within the documentation code generator. Instead, review this pseudocode, which should make sense in a broad way, and amend the code generator snippet to include the base64 encoding of your PDF according 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/.
Before you start coding this part, read on to learn about PDF fields.
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.
What about PDF fields?
But 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 in PDFs.
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.
If you don't use tags there are three alternatives to creating fields (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 can deduce 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 the PDF form fields which helpfully is the exact same JSON schema 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.
iii) Create an embeddable PDF edit page so your users can drag and drop fields directly - see documentation (more information coming soon).
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@legalesign.com for any assistance.