Quickstart
5 steps to get up and running:
- Create an account + API key (see Get verified for API access).
- Confirm credentials are working and get a team ID.
- Send a HTML document to be signed and download it.
- Upload a PDF document and send that to be signed.
API documentation is linked from the top of the page - Rest v1 API. The documentation includes a working code generator. Fill out 'apikeyAuth' with your key and run test queries.
The API is highly versatile, from simple PDF send & sign to complex multi-signer, batched documents with witnessing and approvals, plus teams with user management. In this quick start we'll send a couple of documents in HTML and PDF formats and download them. 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 (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 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. Read how.
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.
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 endpoint's documentation 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. The main event.
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.
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
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:
$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.
Here are three more 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 it and you'll notice it's a UUID prefixed with 'pdf'. The UUID is your pdfID.
Your API PDF resource uri will be - /api/v1/templatepdf/:pdfId/.
Put that into the 'templatepdf' attribute of the send document call.
::: If you will 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 directly - see documentation.
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. :partying_face:
Happy coding! We're here to help, contact support@legalesign.com for any assistance.