Get Started with SignRequest's API using Node.js

This Help Article requires basic Javascript knowledge, for Javascript tutorials check Mdn.

Node.js was released late in 2009, it's open-source and cross-platform, it allows developers to use Javascript as back-end technology. This revolutionized the way back-end development is done and it later included the famous Javascript front-end frameworks that are run via Node.js, such as React or Vue, for example. Javascript has never been so accessible, and in the past decade it expanded as a computer language that runs outside of your browser. 

Get Started

First, make sure you have Node.js installed in your computer, for more info check the official Node.js website: https://nodejs.org/en/download/

Also, make sure you have a Code Editor installed in your machine, like Atom or Visual Studio Code.

SignRequest offers a GitHub repository with the code and examples used here on how to get easily started with SignRequest's API using Node.js and a few Open-Source libraries.

See repository:

https://github.com/SignRequest/signrequest-Node-example

How to send HTTP requests to SignRequest's API using Node.js:

To send HTTP requests via Node.js, you can use superagent, a library that facilitates sending HTTP requests when running Node.js. Nonetheless, you can use other libraries of your choice, such as HTTP, Axios or Request (recently deprecated). 

To create a Free Sandbox Account, check the following page of our documentation: https://signrequest.com/api/v1/docs/#section/Getting-Started/Sandbox-Team

The first thing you should have ready before starting your project is make sure you have a SignRequest subdomain and an API Token in hands, an API Token looks something like this fake Token below:

290b0f2b15s9824g888e534005951e6311hj4j92

Create a directory for your project. You can start a new Node.js project by running the following command in your terminal:

npm init -y

The command above starts a new npm project with a package.json file. 

Make sure you have superagent installed in your project. Run the following command to install it:

npm install superagent

SignRequest Quick Create

You can get started with your first SignRequest using /signrequest-quick-create/ endpoint, for this example the document is stored on a Google Drive and is being sent via file_from_url:

const request = require("superagent");
const baseUrl = "https://yourteam.signrequest.com/api/v1";

const data = {
file_from_url:"https://drive.google.com/file/d/xxxXXXXXxxxxYYYyyyyy/view?usp=sharing",
signers: [
{
email: "name1@provider.com",
order: 1,
},
],
from_email: "name@provider.com",
message: "Hello World",
who: "o",
subject: "Hello World",
],
};

const createSignRequest = () =>
{

request
.post(`${baseUrl}/signrequest-quick-create/`)
.set("Authorization", "Token XXXXXXXXXXXXXXXXXXXXXXX")
.send(data)
.then((response) => {
console.log("Response: ", response.body);
})
.catch(console.error);
};

createSignRequest();

However, SignRequest's API also allows for files to be stored on your local drive. For that, you should encode your file into base64. For that, you can use the File System class in Node.js, together with Buffer.

//Encode document to base64
const fs = require("fs");
const buffer = Buffer.from("./pdf/document.pdf", "binary");
const dataFile = fs.readFileSync(buffer);
const document_base64 = dataFile.toString("base64");

//Optional
//console.log("Base64: ", document_base64);

Using the code above, you can change a few lines in the snippet that generates a SignRequest via /signrequest-quick-create/

const data = 
{
file_from_content: document_base64,
file_from_content_name: "document.pdf",
//rest of your data code below...
};

Another way of sending SignRequests via API is by using templatesb. Firstly, you should access your template page (https://{your_subdomain}.signrequest.com/#/templates) in your SignRequest subdomain and make sure you upload and prepare your template. This can be easily done via our UI, for more help check this article here. When your template is done, you can send it via API using the template parameter:

const data = 
{
template:
`${baseUrl}/templates/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX/`
//rest of your data code below...
};

Embed URLs:

You can easily generate Embed URLs with signing links that can be shared directly with your signers (make sure you are verifying your signers' emails, due to security). Most commonly, Embed URLs are used within <iframe> HTML tags directly. For that, you can assign ids to each one of your signers to whom you wish to generate Embed URLs. For example:

 signers: 
[

{
email: "name1@provider.com",
order: 1,
embed_url_user_id: "signer1234_embedurl"
},
...
]

Differences: /documents/ + /signrequests/ and /signrequest-quick-create/

If you wish to quickly create a SignRequest, you can stick with the Quick-Create method for that. Otherwise, if you need to generate more complex workflows, for example with multi-docs or add attachments, then you can split your SignRequest in two steps. First, create the document via /documents/, either via file_from_url, template or file_from_content, in this step you specify all the prefill_tags that should be merged to your document via external_ids, regardless of the signers yet, after this step, you can send attachments to your document based on id. In the next step, you can create your SignRequest via /signrequests/, with all the specific configurations, the who parameter, including the signers' array, the subject and message of your SignRequest. 

GET requests

Once you send your first SignRequests, you can retrieve data about your requests either having event callbacks setup for your team (documentation page), or sending GET requests to your /documents/ endpoint. Which can also be done based on a document id. 

const getDocs = () => {
request(`${baseUrl}/documents/`)
//or send a document uuid after documents, i.e: /documents/uuid/
.set("Authorization", "Token XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
.then(response => {
console.log("Response: ", response.body)
})
.catch(console.error);
};

getDocs();

Conclusion

Above we showed how it is easy to get started with SignRequest's API using a Node.js application that sends HTTP requests. With the basic examples above, you can expand them to create more complex applications that integrate their servers with SignRequest, or to create automated process for e-signatures. For more information and more advanced details about callbacks and webhooks, please check our API documentation. If you still have questions, don't hesitate to contact our support.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.