Docubee’s Find & Replace API Feature

Our Fields API Allows You to Dynamically Place Text on Documents: Here’s How it Works

Docubee’s Fields API feature acts as a “find and replace”, placing fields in the designated spot on a document automatically. The API will dynamically look for the new text areas you’ve designated and place the fields in the appropriate area.

Use Case: Rental Agreements
The Fields API is a perfect solution for single or multi-page documents requiring multiple signatures. Using a rental agreement as our example, the API can automatically detect all signature fields and place legally binding eSignature boxes for customers to sign. This would appear anywhere in the document that says “Signature”.

Before You Begin

The first step is to ensure that you have a Docubee account. Once your account is set up, you’ll need to create an API token.

You’ll also need a document with placeholders. Documents using anchor strings must be searchable documents (i.e. Word Documents or PDF). You can use your favorite document editor to make your own, or you can use the one we’ve made for this article here: https://github.com/ontask-io/fields-api-demo-nodejs/blob/master/documents/fields-doc.pdf

Our sample document looks like this:

and uses placeholders that look like #this#, a text string beginning and ending with a pound sign. Note, your placeholders do not have to follow this convention; you can use any character string you wish as long as you configure your Fields API call accordingly. 

Setting Up Your API Token:

Your API token will be sent as a header to authenticate your requests (this a requirement to use the Docubee API). Follow this link for information on how you can create your own: https://www.docubee.com/resources/help-center/generating-a-token-for-api-access/

For this demo, your token will need to have at least the following permissions:

a. Get documents

b. Set document fields

c. Upload documents

Find & Replace with the Fields API:

For this demo, we are using Node.js (v16.0.0) with the node-fetch package, and Visual Studio Code. You can download the completed project folder here: https://github.com/ontask-io/fields-api-demo-nodejs

1. To begin, create a new directory called docubee-fields-demo. Then, open this directory in Visual Studio Code (or your IDE of choice) and run the npm init command (accepting all the default options) in a terminal to create a new node project. Run the npm install node-fetch command to download the node-fetch package.
2. Open the package.json file in the root of the docubee-fields-demo directory. Toward the end of the file, on the last line in the root object, add the following line (line 14 here, but yours may be slightly different) to configure this project to use JavaScript modules

3. Then, create a new file called index.js and a subdirectory called documents within the docubee-fields-demo directory. Put the placeholder document you made or downloaded earlier in the documents directory.
 

Your directory structure should now look like this:

4. Open the index.js file and add the following code on lines 1-5, replacing the <YOUR-API-TOKEN> placeholder with your API token:

1: import fetch from 'node-fetch';
2: import { readFileSync } from 'fs';
3:
4: const ontaskUrl = 'https://docubee.app';
5: const apiToken = '';

5. In order to place fields on the placeholder document, you’ll need a documentId, which represents a document uploaded into the Docubee system. You’ll get that by using the Documents – Upload API. In index.js, add the following code on lines 7-20: Here, you declare your imports from node-fetch and fs. Then, you initialize variables to hold the Docubee base URL and your API token.

7:  const uploadDocument = async (pathToFile) => {
8:      const response = await fetch(`https://docubee.app/api/v2/documents`, {
9:          body: readFileSync(pathToFile),
10:         headers: {
11:             Authorization: apiToken,
12:             'Content-Type': 'application/pdf'
13:         },
14:         method: 'POST'
15:     });
16:
17:     const { documentId } = await response.json();
18:   
19:     return documentId;
20: }

The uploadDocument() function takes a file path as it’s parameter, and makes a call to the Docubee API to upload the document at the file path into Docubee. It returns a documentId, which you’ll need to use the Fields API.

Next, let’s make a function that will take this documentId and place fields on the document’s placeholders.

6. Add the following code to lines 22-66 in index.js:

22: const placeFieldsOnDocument = async (inputDocumentId) => {
23:     const response = await fetch(`${ontaskUrl}/api/v2/documents/${inputDocumentId}/fields`, {
24:         body: JSON.stringify({
25:             fields: [
26:                 {
27:                     anchorString: '#checkbox#',
28:                     name: 'TestCheckbox',
29:                     removeAnchorString: true,
30:                     required: true,
31:                     type: 'checkbox'
32:                 },
33:                 {
34:                     anchorString: '#date#',
35:                     name: 'TestDate',
36:                     removeAnchorString: true,
37:                     required: true,
38:                     type: 'date'
39:                 },
40:                 {
41:                     anchorString: '#initials#',
42:                     name: 'TestInitials',
43:                     removeAnchorString: true,
44:                     required: true,
45:                     type: 'initials'
46:                 },
47:                 {
48:                     anchorString: '#signature#',
49:                     name: 'TestSignature',
50:                     removeAnchorString: true,
51:                     required: true,
52:                     type: 'signature'
53:                 }
54:             ]
55:         }),
56:         headers: {
57:             Authorization: apiToken,
58:             'Content-Type': 'application/json'
59:         },
60:         method: 'PUT'
61:     });
62:
63:     const { documentId } = await response.json();
64:
65:     return documentId;
66: }

The placeFieldsOnDocument() function takes the inputDocumentId which represents the documentId returned from your Documents – Upload API call. The body of the Fields API is an array of objects where each object represents a text string that will be replaced by your fields throughout the document.

There are 5 supported field types you can configure in the body of the request: 

1. checkbox
2. date
3. initials
4. signature
5. text

Each field type has configuration settings that allows you to tune how they are presented. The value of the anchorString is the placeholder text that will be replaced. If multiple instances of the anchor string are found in the document, the specified field type will be applied for each. See our documentation here for more information on how to configure the Fields API request body.

Now that your functions are set up, let’s run it!

7. In index.js, add the final piece of code on lines 68-74:

68: (async () => {
69:     const inputDocId = await uploadDocument('./documents/fields-doc.pdf');
70:     console.log(`inputDocId: ${inputDocId}`);
71:   
72:     const fieldsDocId = await placeFieldsOnDocument(inputDocId);
73:     console.log(`fieldsDocId: ${fieldsDocId}`);
74: })();

Here, you call an anonymous function that calls your two functions you defined earlier in steps 5 and 6. We print out the documentId returned from each; they should be exactly the same. This is because we reuse the document reference after we process and apply the fields to it with the Fields API.

The fields you create are specific to Docubee, and won’t appear on the document outside of Docubee. When the fields are applied to the document, it will look like this to the user:

In the fill & sign task, the user will be able to interact and enter data into the fields. They can check the checkbox, pick a date, enter text, and sign the fields that you replaced with the Fields API.

Next Steps:

Now that you have a document with fields, you can use the documentId to start a workflow that sends out our document for signature! Looking for information on how to interact with workflows using the API? Read our article here:  https://resources.ontask.io/c/ontask-api-how-to-st?x=X3Dlw4