DEV Community

Cover image for Embed Secure eSignatures into Your App with Foxit API
Raymond Camden for Foxit Developers

Posted on • Originally published at developer-api.foxit.com

Embed Secure eSignatures into Your App with Foxit API

Foxit eSign is an electronic signature solution that enables individuals and businesses to securely sign, send, and manage documents online. It streamlines the document signing process by allowing users to create legally binding eSignatures, prepare forms, and track document status in real time. With features like reusable templates, automated workflows, and audit trails, it enhances productivity and reduces the need for manual paperwork.

At the simplest level, a user can log into the eSign dashboard and handle 100% of their signing needs. So for example, they can upload a Microsoft Word template and then drag and drop fields that will be used during the signing process. I did this with a simple Word document. After uploading, I was given an easy to use editor to drag and drop fields:

Picture of eSign editor

In the screen shot above, I've added three fields to my document. The first is a date field. The second is for the signers name. The last field is the actual signature spot. Each of these fields have many options, and your own documents could have far more (or heck, even less) fields. The point is - you're allowed to design these forms to meet whatever need you may have. Also note that you can do all of this directly within Word, as well. Our docs show how to add fields directly into Word that will become enabled in the signing process.

Once you've got your template in a nice place, you can initiate the signing process right from the app. The dashboard also gives you a full history and audit trail of that process (have they signed yet? when did they do it? who signed?) which is handy. But, of course, you're here because you're a developer, and you're probably asking yourself - can we automate this? The answer? Of course!

If you would rather watch an introduction to the API, enjoy the video below!

eSign Via API

Before we begin digging into the APIs, be sure to take a quick look at the API Reference. As I've stated a few times, the signing process itself can be incredibly complex. For example, there may be 2, 3, or more people who need to sign a document, and in a particular order. Also, remember that I shared that the template process of adding fields and such can be done entirely in Word itself. This is to say that our look here is going to focus on a simple example of signing. But there's nothing to stop the creation of more advanced, flexible workflows.

The first step in any API usage will be authentication. When you have an eSign account with API access, you'll be given a client_id and client_secret value, both of which need to be exchanged for an access token at the appropriate endpoint. Here's a simple example of this with Python:

CLIENT_ID = os.environ.get("CLIENT_ID")
CLIENT_SECRET = os.environ.get("CLIENT_SECRET")

def getAccessToken(id, secret):
    url = "https://na1.foxitesign.foxit.com/api/oauth2/access_token"
    payload=f"client_id={id}&client_secret={secret}&grant_type=client_credentials&scope=read-write"
    headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
    }

    response = requests.request("POST", url, headers=headers, data=payload)

    token = (response.json())["access_token"]
    return token

access_token = getAccessToken(CLIENT_ID, CLIENT_SECRET)
Enter fullscreen mode Exit fullscreen mode

All the rest of the demos will make use of this method, and at the end of this post I'll share GitHub links for the source.

Kicking Off the Signing API Process

Now that we've authenticated with the API, our code can start doing... well, everything. The first thing we will add is a signing process with the template I showed above. From the dashboard itself I was able to make note of the template ID, 392230, but note that there's APIs for working with templates where that could be done via code as well.

To start the signing process, we can use the Create Envelope from Template endpoint. You can think of an envelope as a set of documents a user has to sign. For our demo, it's one, but you can include multiple documents. If you look at the API reference example, you'll see a large input body. As I've said, and will probably keep saying, the electronic signing process can be quite complex. For our simple demo, however, we just need to know the name of the person we're asking to sign the document and their email address. I whipped up this simple Python utility to enable that:

def sendForSigning(template_id, first_name, last_name, email, token):
    url = "https://na1.foxitesign.foxit.com/api/templates/createFolder"
    body = {
        "folderName":"Sending for Signing",
        "templateIds":[template_id],
        "parties":[
        {
            "permission":"FILL_FIELDS_AND_SIGN",
            "firstName":first_name,
            "lastName":last_name,
            "emailId":email,
            "sequence":1
        }
        ],
        "senderEmail":"raymond_camden@foxitsoftware.com"
    }

    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("POST", url, headers=headers, json=body)
    return response.json()
Enter fullscreen mode Exit fullscreen mode

Make note that parties is an array of one person, as only one person is needed in the process. Also note that permission is required as it defines the role that person will play in the party.

Calling this method is simple:

# Hard coded template id
tid = "392230"

sendForSigningResponse = sendForSigning(tid, "Raymond", "Camden", "raymondcamden@gmail.com", access_token)
Enter fullscreen mode Exit fullscreen mode

The result of this call is a large set of data. But for now, we can live with just the ID of the evenlope created:

envelopeId = sendForSigningResponse['folder']['folderId']
print(f"ID of the envelope created: {envelopeId}")
Enter fullscreen mode Exit fullscreen mode

** Note: You'll see 'folder' referenced in the API endpoints and results, but the eSign API is migrating to the 'envelope' term instead. **

A few seconds after running this code, the email showed up in my account:

Email in regards to signing

Obviously at this point, I could sign it... but what if I didn't?

Sending out Electronic Reminders

One way to help ensure your important documents get signed is to remind the people who need to sign that - well, they need actually sign the document. To enable this, we can use the Send Signature Reminder endpoint. All it needs is the ID of the envelope created earlier (and again, see my note about envelope vs folder):

def sendReminder(envelope_id, token):   
    url = "https://na1.foxitesign.foxit.com/api/folders/signaturereminder"
    body = {
        "folderId":envelope_id
    }
    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("POST", url, headers=headers, json=body)
    result = response.json()
    return result
Enter fullscreen mode Exit fullscreen mode

Calling this just required the access token and ID:

access_token = getAccessToken(CLIENT_ID, CLIENT_SECRET)
result = sendReminder(envelope_id, access_token)
Enter fullscreen mode Exit fullscreen mode

As you can expect, this sends an email reminder:

Email reminder

Ok, But Did They Sign Their Document Yet??

So far, you've seen an example of sending out a document for signing as well as politely reminding the person to do their job. How can you tell if they've completed the process? For this, we can turn to the Get Envelope Details endpoint. It's also rather simple in that it just needs the envelope ID value from before. Once again, here's a wrapper to that API built in Python:

def getStatus(envelope_id, token):  
    url = f"https://na1.foxitesign.foxit.com/api/folders/myfolder?folderId={envelope_id}"

    headers = {
        'Authorization': f'Bearer {token}',
    }

    response = requests.request("GET", url, headers=headers)
    result = response.json()
    return result
Enter fullscreen mode Exit fullscreen mode

And the call:

result = getStatus(envelope_id, access_token)

print(f"Envelope status: {result['folder']['folderStatus']}")
Enter fullscreen mode Exit fullscreen mode

While there's a lot of important information returned, we can output just the status to see at a high level what state the process is currently in.

Given the example I've shown so far, the status of the envelope is SHARED. Let's actually click the link:

Document prepared for signing

In the screenshot above, notice how the date is already filled to today's data. Also note that name was prefilled as eSign knows who it was sent to. All I need to do is click and sign. Once I do, the same code above will now return EXECUTED.

Next Steps

Wondering where to go next? If you are completely new to eSign, check out the main homepage for an introduction. You can also check out the Foxit eSign YouTube channel for lots of good video content on the service. If you want a copy of the code I showed in this post, you can find all three examples here: https://github.com/foxitsoftware/developerapidemos/tree/main/esign. Finally, don't forget to visit our forums and bring your questions!

Top comments (0)