API quickstart with the Python SDK

A Python SDK can be generated using the OpenAPI3 specification of our API and openapi generator. The package contains its own documentation (in docs/), but the examples below will show you how to get started.

Get your API Key

1. Sign up for a trial account. Configure for API when prompted, and email support to get an API Key. You need to show a level of understanding about using REST API, include a brief summary of your programming/REST experience.

2. Once issued, your API key will be available in the web app. You will see you are in sandbox - add any emails where you will send your test documents.

3. Your api key goes in the "Authorization" header, and takes the form: Apikey username:secret. Your username and secret will be clearly indicated in the web app.

Install

pip install git+https://github.com/legalesign/Legalesign-V1-Python.git

Configure

Replace username and secret with your API key details.

import openapi_client
configuration = openapi_client.Configuration(
    host = "https://eu-api.legalesign.com/api/v1",
    api_key = {
        'Authorization': 'ApiKey username:secret'
    }
)

Test a GET request

Begin by making sure you can make a plain GET request, to ensure your Auth is configured properly.

groups = openapi_client.GroupApi(api_client)
groups.get_groups()

If successful you'll get JSON print of your group information. If not double check you have your Authorization value correct.

This following code gets any documents waiting to be signed, a common use-case.

docs = openapi_client.DocumentApi(api_client)
docs.get_documents()

The 'get_statuses()' and 'get_status()' calls are a faster ways to query for basic doc information.

You should be starting to understand how openapi works. Go back to the package Readme file, and you will see all the API objects to try, and all their methods.

Test a POST request

Next we will send some custom HTML for signing in one API call. Then we'll upload a PDF and send that.

Send an HTML document to get signed

Here's a small amount of HTML for demo purposes, containing one signature element. Replace the group, name and email values.

text = "<h1>Test doc</h1><p>Test doc for testing, <span class=\"field\" data-optional=\"false\" data-name=\"Please add your ...\" data-signee=\"1\" data-type=\"signature\" data-options=\"\"> ....... </span>"

postdata = {'group': '/api/v1/group/my-group/', 'name': 'test document', 'text': text, 'signers': [{'order': 0, 'email': 'my@email.com', 'firstname': 'Joe', 'lastname': 'Blogs'}],'do_email': True}

docs.post_document(postdata)

How do we know it went through? OpenAPI throws an exception for non 2XX responses. You will want to put all your requests into a try/catch block.

Every time you POST, you will probably want the new object ID. It's in the Location header of the response. The documented methods from openapi, however, do not return any objects. You can find the Location header through the api client, like so:

new_doc_resource_uri = docs.api_client.last_response.getheader('Location')

There are non-documented POST methods which do return the response directly. Just add '_with_http_info' to the end of the POST method. For example:

response = doc.post_document_with_http_info(postdata)
status_code = response[1]
headers = response[2]
doc_resource_uri = headers.get('Location')

How to get response headers from python openapi_generator SDK: append 'with_http_info' to the method name of your POST request. The response is a 3 item list comprising the response body, the status code, and the headers.

Upload and send a PDF

You will most likely use text-tags within your PDFs, to define where people will sign or fill out any forms.

Learn more about text tags.

Lets upload a PDF using the 'with_http_info' version of the POST request to get the ID:

import base64

pdf = openapi_client.TemplatepdfApi(api_client)

pdfdata = base64.b64encode(open('myfile.pdf','rb').read()).decode()

pdfresponse = pdf.post_pdf_template_with_http_info(
     {'title': 'test of tagged doc', 'group': '/api/v1/group/my-group/',
     'pdf_file': pdfdata, 'process_tags': True}
)

Because we set process_tags to true, all the tags have been processed so your PDF is ready to go.

As before, we need the ID for the PDF so we can send it.

# 1. get ID of templatepdf object you just uploaded:

templatepdf_id = pdfresponse[2].get('Location')

# 2. get the Document API if you haven't already:

docs = openapi_client.DocumentApi(api_client)

# 3. construct post data and send, replace the group name and email (don't forget to use a sandbox email):

postdata = {
   'group': '/api/v1/group/my-group/',
   'name': 'test2', 'templatepdf':templatepdf_id,
   'signers': [{'order': 0, 'email': 'my@email.com', 'firstname': 'my', 'lastname': 'name'}],
   'do_email': True
}

docs.post_document(postdata)

OR

docresponse = docs.post_document_with_http_info(postdata)
status  = docresponse[1]
doc_id = docresponse[2].get('Location')

Get coding

Be sure to read the documentation. We had to dig around in the python source code a little but it is well laid out and consistent. Some common gotchas are:

1. When you create a document, ensure your signers information is a dictionary WITHIN a list (there may be more than 1 signer).

2. 404 may come back if your object references are wrong.

3. 401 will come back if you are in sandbox and try and send a document to someone not in your sandbox email list.

Happy coding!