NAV
cURL Node.js Python
Docubee API Reference

Overview

Docubee gives you an easy-to-use, flexible, and affordable cloud-based platform to take control of all your documents and forms. Your reusable workflows on our platform take the frustration out of collecting customer and employee information on paper forms or fillable PDFs by routing those forms online through a participants browser.

Create simple to complex routing processes, track forms on your dashboard as they travel through review, collect digital signatures, and ensure that everyone is using the most accurate, up-to-date document versions. Go from manual to modern document and forms administration with Docubee.

Getting Started

This documentation lists the routes provided by our API that will assist in integration with your site or application. To use these endpoints, you will need a security token for the workspace that owns the workflow(s) or other resources you are working with.

Before you begin, you will need to gain access to the API.

To sign up for a plan, see our pricing page or start a 14-day free trial.

  1. Sign up for an Docubee account.
  2. Create a workflow.
  3. Use the Docubee user interface or the API to upload documents and start workflows.

Base URL

The base URL for the Docubee API is:

https://docubee.app/

Postman Collection

You can download the Docubee API Postman collection here:

Sample Code

To help get you started we’ve created samples that show how to use our eSignature APIs. The sample code allows you to get your own projects up and running in no time. You’ll also need to make sure and get your free API key to configure in the code samples before you get started.

Authentication

To authorize, use the workspace access token in the request headers like this :

curl https://docubee.app/api/v2/fake/example/route \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/fake/example/route', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/fake/example/route'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

Make sure to replace WORKSPACE-ACCESS-TOKEN with your workspace access token.

Docubee requires a valid workspace access token to allow access to the API.

Generate an Access Token

  1. Log in to your Docubee account by visiting https://docubee.app/login.
  2. Click the settings gear icon at the bottom of the left navigation bar.
  3. In the left sidebar, select the workspace for which you want to create an access token.
  4. Expand the ACCESS TOKENS section.
  5. Choose a name for this API connection.
  6. Choose the permission level for this token. Required token permissions are listed for each API route below.
  7. Click GENERATE TOKEN.
  8. Copy the token to your clipboard by clicking the copy icon or use shortcut keys on your keyboard.

Docubee expects for the workspace access token to be included in all API requests to the server in a header that looks like the following:

Authorization: WORKSPACE-ACCESS-TOKEN

Documents

List Documents

curl https://docubee.app/api/v2/documents \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/documents', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/documents'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documents": [
    {
      "contentType": "application/pdf",
      "createdAt": "2022-08-12T01:02:03.000Z",
      "documentId": "241aad14-7ea5-4731-8c97-284299868cd6",
      "documentName": "MyUploadedFile.pdf",
      "modifiedAt": "2022-08-12T01:02:03.000Z",
      "path": "/MyUploadedFile.pdf"
    }
  ]
}

Retrieve a list of documents from the My Document section of Docubee

List Documents

GET /api/v2/documents

Required Token Permissions

List documents

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Download

curl https://docubee.app/api/v2/documents/:documentId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -o 'path/to/file.extension'

const fetch = require('node-fetch');
const fs = require('fs');

const response = await fetch('https://docubee.app/api/v2/documents/:documentId', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const buffer = await response.buffer();
fs.writeFileSync('/path/to/file.extension', buffer);

import requests

url = 'https://docubee.app/api/v2/documents/:documentId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
with open('path/to/file.extension', 'wb') as fd:
  fd.write(response.content)

The above request returns a binary file:

<<file bytes>>

Download a document from Docubee.

Download a Document

GET /api/v2/documents/:documentId

Required Token Permissions

Get documents

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Upload

curl -X POST https://docubee.app/api/v2/documents \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/pdf' \
  --data-binary '@path/to/file.pdf'

const fetch = require('node-fetch');
const fs = require('fs');

const fileContents = fs.readFileSync('path/to/file.pdf');

const response = await fetch('https://docubee.app/api/v2/documents', {
  body: fileContents,
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/pdf'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/documents'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/pdf'
}
data = open('path/to/file.pdf', 'rb').read()

response = requests.post(url=url, headers=headers, data=data)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documentId": "1cb18b1f-6872-46c5-9f11-520f1b432ffc"
}

Upload a new document to Docubee for use in a workflow. The body of this request is the binary document you would like to upload.

Upload a Document

POST /api/v2/documents

Required Token Permissions

Upload documents

Headers

Header Type Description
* Authorization string Your workspace access token.
* Content-Type string The MIME type of the supplied document.
collection string, valid values: [ 'default', 'my-documents' ] The document collection to store this document
filename string Custom filename
path string File path within the collection (Required if the collection is 'my-documents')

* denotes required

Body

A binary document.

Update Existing Document

curl -X PUT https://docubee.app/api/v2/documents/:documentId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/pdf' \
  --data-binary '@path/to/file.pdf'

const fetch = require('node-fetch');
const fs = require('fs');

const fileContents = fs.readFileSync('path/to/file.pdf');

const response = await fetch('https://docubee.app/api/v2/documents/:documentId', {
  body: fileContents,
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/pdf'
  },
  method: 'PUT'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/documents/:documentId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/pdf'
}
data = open('path/to/file.pdf', 'rb').read()

response = requests.put(url=url, headers=headers, data=data)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documentId": "1cb18b1f-6872-46c5-9f11-520f1b432ffc",
  "revisionId": "539a7bfd-db0f-4d6e-99cf-3f82f656bd4e"
}

Upload a new revision of a document to Docubee to replace an existing document. This new revision will retain related information such as placed field locations.

Update an Existing Document

PUT /api/v2/documents/:documentId

Required Token Permissions

Upload documents

Headers

Header Type Description
* Authorization string Your workspace access token.
* Content-Type string The MIME type of the supplied document.
filename string Custom filename

* denotes required

Body

A binary document.

Delete Existing Document

curl -X DELETE https://docubee.app/api/v2/documents/:documentId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/documents/:documentId', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  },
  method: 'DELETE'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/documents/:documentId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.delete(url=url, headers=headers)
print(response.json())

Permanently deletes an existing document.

Delete an Existing Document

DELETE /api/v2/documents/:documentId

Required Token Permissions

Delete documents

Headers

Header Type Description
* Authorization string Your workspace access token.

* denotes required

Fields

curl -X PUT https://docubee.app/api/v2/documents/:documentId/fields \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "formDefinitionId": "TestFormDefinition", "fields": [{ "anchorString": "AnchorText", "name": "TestDisplayName", "removeAnchorString": true, "required": true, "type": "signature" }]}'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/documents/:documentId/fields', {
  body: JSON.stringify({
    formDefinitionId: 'TestFormDefinition',
    fields: [
      {
        anchorString: 'AnchorText',
        name: 'TestDisplayName',
        removeAnchorString: true,
        required: true,
        type: 'signature'
      }
    ]
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'PUT'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/documents/:documentId/fields'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'formDefinitionId': 'TestFormDefinition',
  'fields': [
    {
      'anchorString': 'AnchorText',
      'name': 'TestDisplayName',
      'removeAnchorString': True,
      'required': True,
      'type': 'signature'
    }
  ]
}

response = requests.put(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documentId": "e0e513ec-7086-4718-b4da-f0d5e2abe25b",
  "formDefinitionId": "TestFormDefinition",
  "templatedFieldsCount": 1
}

Set fields on a document by using anchor strings for dynamic placement.

Set Document Fields

PUT /api/v2/documents/:documentId/fields

URL Parameters

Parameter Description
documentId The ID of the document to set fields on

Required Token Permissions

Set document fields

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* fields fieldObjectArray An array of field objects that specify where to set fields on the document.
formDefinitionId string matching ^[a-zA-Z0-9_-]+$ When set this string defines a named formDefinition that can be used in the start signature process. Default is formDefinition.

* denotes required

fieldObjectArray

Key Details Description
* anchorString string, must be unique The string in the document to search for and apply the field to.
* name string Label the person filling out the form will see for this field.
* type string, valid values: [ "checkbox", "date", "initials", "radiogroup", "signature", "text" ] The type of field to replace this anchor string with
formRoleId string Defines which signer this field is assigned to. Default is formRole1.
height number The height of the field. See table below for default values. Units are in points (1/72 of an inch)
width number The width of the field. See table below for default values. Units are in points (1/72 of an inch)
xOffset number The value to offset the field on the x-axis from the original anchor string position. Value can be positive (move right) or negative (move left). Default is 0. Units are in points (1/72 of an inch)
yOffset number The value to offset the field on the y-axis from the original anchor string position. Value can be positive (move up) or negative (move down). Default is 0. Units are in points (1/72 of an inch)
required boolean Marks the field as required for the person filling out the form. Default is false.
propertyName string, only valid for types [ "checkbox", "date", "radiogroup", "text" ], must be unique When set this will capture the data submitted by the person filling out the form and use this key to identify it later in the workflow. Default is null.
removeAnchorString boolean When set this will redact the anchor string from the document. Default is false.
values array of strings, only valid for type "radiogroup" A list of values that will be assigned to matched entries in order. If this is not provided (or more matches than values exist) any remaining will be provided a value of "Option 1", "Option 2", etc.

* denotes required

Field Object Defaults

Units are in points (1/72 of an inch)

Field Type Height Width
checkbox 15 15
radiogroup 15 15
date 24 210
initials 24 24
signature 24 210
text 24 210

Workflows

List Workflows

curl https://docubee.app/api/v2/workflowTemplates \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON array structured like this:

[
  {
    "description": null,
    "instanceCount": 0,
    "name": "Expense Approval",
    "permissions": [
      {
        "allowedTenantId": "public",
        "requiredPermission": null
      }
    ],
    "runningInstances": 0,
    "state": "active",
    "templateId": "1a3042d8-1713-4556-ba41-7f09b515bd34",
    "tenantId": "b3bbd233-1205-4c0a-9ba6-b6560e4ea438"
  },
  {...}
]

This endpoint retrieves a list of workflows in the workspace the access token belongs to.

List Workflows

GET /api/v2/workflowTemplates

Required Token Permissions

List workflows

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Create New

curl -X POST https://docubee.app/api/v2/workflowTemplates \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "templateName": "My Workflow Template" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates', {
  body: JSON.stringify({
    templateName: 'My Workflow Template'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'templateName': 'My Workflow Template'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "templateId": "7ca7abc9-ed8c-4295-82f5-7b32cd8241c2"
}

Create a new, empty workflow.

Create Workflow

POST /api/v2/workflowTemplates

Required Token Permissions

Manage workflows

Headers

Header Type Description
Authorization string Your workspace access token. (Required)
Content-Type string application/json (Required)

Body

Key Type Description
templateName string The title of this workflow. Default is Untitled Workflow.

Export

curl https://docubee.app/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -o 'path/to/export.docubee-workflow'

const fetch = require('node-fetch');
const fs = require('fs');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates/:templateId', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const buffer = await response.buffer();
fs.writeFileSync('/path/to/export.docubee-workflow', buffer);

import requests

url = 'https://docubee.app/api/v2/workflowTemplates/:templateId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
with open('path/to/export.docubee-workflow', 'wb') as fd:
  fd.write(response.content)

The above request returns a binary file:

<<file bytes>>

Export the current workflow for archiving. The resulting file can be imported from within the Workflow Builder in Docubee as well as the Import Workflow API.

Export Workflow

GET /api/v2/workflowTemplates/:templateId

Required Token Permissions

Manage workflows

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Import

curl -X PUT https://docubee.app/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/docubee' \
  --data-binary '@path/to/file.docubee-workflow'

const fetch = require('node-fetch');
const fs = require('fs');

const fileContents = fs.readFileSync('path/to/file.docubee-workflow');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates/:templateId', {
  body: fileContents,
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/docubee'
  },
  method: 'PUT'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates/:templateId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/docubee'
}
data = open('path/to/file.docubee-workflow', 'rb').read()

response = requests.put(url=url, headers=headers, data=data)
print(response.json())

The above request returns a JSON object structured like this:

{
  "published": false,
  "templateId": "1cb18b1f-6872-46c5-9f11-520f1b432ffc"
}

Import a previously exported .docubee-workflow. A valid file can be retrieved from the Export Workflow API or from the Docubee workflow builder UI.

Import Workflow

PUT /api/v2/workflowTemplates/:templateId

Required Token Permissions

Manage workflows

Headers

Header Type Description
Authorization string Your workspace access token. (Required)
Content-Type string application/docubee (Required)

Query Parameters

Parameter Description
publish Whether to immediately publish the workflow after loading the imported definition:true or false. Default is false.

Body

A valid .docubee-workflow export file

Get Start Form

curl https://docubee.app/api/v2/workflowTemplates/:templateId/startForm

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates/:templateId/startForm');

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates/:templateId/startForm'

response = requests.get(url=url)
print(response.json())

The above request returns a JSON object structured like this:

{
  "workflowOwner": "...",
  "workflowOwnerData": {
    "owningOrgTenantId": "...",
    "owningOrgName": "API Example",
    "owningOrgUserId": "...",
    "owningGroupTenantId": "...",
    "owningGroupName": "My Example Workspace",
    "owningOrgUserConfirmed": true
  },
  "pageDefinition": {
    "page": {
      "title": "Workflow API Example",
      "description": ""
    },
    "useWaitPage": true,
    "actions": {...},
    "elementId": "...",
    "form": [
      {
        "disabled": false,
        "label": "Sender Name",
        "size": "medium",
        "validation": {
          "required": true
        },
        "fieldId": "2084b4e9-0361-4300-856b-54983f5214ae",
        "permissions": false,
        "type": "text",
        "name": "Sender_Name"
      }
    ]
  }
}

This endpoint retrieves the fields from a workflow's start form.

Get Workflow Start Form Data

GET /api/v2/workflowTemplates/:templateId/startForm

URL Parameters

Parameter Description
templateId The ID of the workflow (Can be found from the LIST workflows call)

Start Workflow

curl -X POST https://docubee.app/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "File_Upload": "VALID_DOCUMENT_ID", "Sender_Name": "Steve" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates/:templateId', {
  body: JSON.stringify({
    File_Upload: 'VALID_DOCUMENT_ID',
    Sender_Name: 'Steve'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates/:templateId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'File_Upload': 'VALID_DOCUMENT_ID',
  'Sender_Name': 'Steve'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "instanceId": "ebe9831c-2d09-4bf5-9fcd-236ea14d2509",
  "redirectUrl": "https://docubee.app/workflows/url/to/next/task"
}

This endpoint starts a workflow.

Start Workflow

POST /api/v2/workflowTemplates/:templateId

Required Token Permissions

Start workflow instances

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

URL Parameters

Parameter Description
templateId The ID of the workflow (Can be found from the LIST workflows call)

Body

The request body consists of fields on the start form represented as a JSON object. For document upload fields, you must provide the documentId returned from a previous call to upload a document.

Workflow Instances

List Instances

curl https://docubee.app/api/v2/workflowTemplates/:templateId/instances \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/workflowTemplates/:templateId/instances', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/workflowTemplates/:templateId/instances'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "instances": [
    {
      "completionDate": null,
      "details": "Sent for Follow Up",
      "instanceId": "240b05ea-0391-431e-8af1-47f1c17be30b",
      "startDate": "2021-04-18T10:41:02.000Z",
      "status": "in-progress",
      "templateId": "d87347b9-898e-4c01-8924-71b95d233817",
      "title": "ABC Corporation Contract"
    },
    {
      "completionDate": "2021-04-14T18:50:42.000Z",
      "details": "Workflow Completed",
      "instanceId": "4917bf5c-96a0-4e1f-a57d-1abdb4b06b3e",
      "startDate": "2021-04-13T15:22:10.000Z",
      "status": "completed",
      "templateId": "d87347b9-898e-4c01-8924-71b95d233817",
      "title": "XYZ Corporation Contract"
    },
    {...}
  ],
  "next": "ac875474"
}

This endpoint retrieves a list of instances for a specified workflow.

List Instances

GET /api/v2/workflowTemplates/:templateId/instances

Required Token Permissions

Get instance data

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

URL Parameters

Parameter Description
templateId The ID of the workflow (Can be found from the LIST workflows call)

Query Parameters

Parameter Description
cursor A value returned as the next property in a previous response. Used to fetch subsequent pages of results. Default is null.
expand Comma-separated list of additional data to retrieve along with your request. The only allowed value currently is currentTasks, which will return an array of all currently available user tasks in the response.
orderBy Determines how the instances returned in the response will be ordered. Allowed values are startDate or endDate. Default is startDate.
status Limits the results to only those with a specific status. Multiple status values can be provided, separated by commas. Allowed values are all, in-progress, completed, canceled, removed or error. Default is all.

Pagination

This endpoint returns up to 50 instances per request. If there are more additional records available, the response will contain an additional next property, which can be passed in a subsequent request as cursor. When retrieving the last instances, there will be no next property.

List Instance Properties

curl https://docubee.app/api/v2/instances/:instanceId/properties \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/instances/:instanceId/properties', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/instances/:instanceId/properties'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "properties": {
    "Sender_Name": "Steve",
    "Recipient_Name": "Jack"
  }
}

This endpoint retrieves a list of properties unique to the workflow instance.

List Instance Properties

GET /api/v2/instances/:instanceId/properties

Required Token Permissions

Get instance properties

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

List Instance Documents

curl https://docubee.app/api/v2/instances/:instanceId/documents \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/instances/:instanceId/documents', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/instances/:instanceId/documents'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documents": [
    {
      "documentId": "bb8141e0-626e-48e5-9197-b1f13317ac2c",
      "propertyName": "Waiver",
      "fileExtension": "pdf",
      "filename": "ExamplePDF.pdf",
      "modifiedDate": "2021-04-14T18:50:42.000Z"
    },
    {
      "documentId": "bb8141e0-626e-48e5-9197-b1f13317ac2c",
      "propertyName": "File_Upload",
      "fileExtension": "pdf",
      "filename": "ExampleUploadedFile.pdf",
      "modifiedDate": "2021-04-15T18:50:42.000Z"
    }
  ]
}

This endpoint retrieves a list of documents unique to the workflow instance.

List Instance Documents

GET /api/v2/instances/:instanceId/documents

Required Token Permissions

List instance documents

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

List Instance Tasks

curl https://docubee.app/api/v2/instances/:instanceId/tasks \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/instances/:instanceId/tasks', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/instances/:instanceId/tasks'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "tasks": [
    {
      "assignee": "steve@docubee.app",
      "assigneeDisplayName": "Steve Wilson",
      "assigneeGeolocation": "27.9818072,-82.4727055",
      "assigneeIpAddress": "127.0.0.1",
      "completionDate": null,
      "label": "Sign Document",
      "startDate": "2022-02-14T22:52:44.000Z",
      "status": "available",
      "taskId": "dc2985b3-3e12-45a3-ae36-b752492d7eef"
    },
    {
      "completionDate": "2022-02-14 22:53:21.000Z",
      "label": "Sent for Signature",
      "startDate": "2022-02-14 22:53:21.000Z",
      "status": "milestone"
    },
    {
      "assignee": "Anonymous",
      "assigneeDisplayName": "Anonymous",
      "assigneeIpAddress": null,
      "assigneeGeolocation": null,
      "completionDate": "2022-02-14 22:53:21.000Z",
      "label": "Prepare Fields",
      "startDate": "2022-02-13T18:13:44.000Z",
      "status": "completed",
      "taskId": "df534f48-8dc7-11ec-a834-0242ac120002"
    }
  ]
}

This endpoint retrieves a list of tasks and milestones either completed or available for the instance.

List Instance Tasks

GET /api/v2/instances/:instanceId/tasks

Required Token Permissions

List instance tasks

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Query Parameters

Parameter Description
status Comma-separated list of task status values to return. Accepted values are available, completed, milestone or all. Default is all.

Cancel Instance

curl -X DELETE https://docubee.app/api/v2/instances/:instanceId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/instances/:instanceId', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  },
  method: 'DELETE'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/instances/:instanceId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.delete(url=url, headers=headers)
print(response.json())

This endpoint cancels an in-progress or removes a completed workflow instance.

Cancel Instances

DELETE /api/v2/instances/:instanceId

Required Token Permissions

Cancel workflow instances

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

URL Parameters

Parameter Description
instanceId The ID of the workflow instance (Can be found from the LIST instances call)

Signature API

To get started with the Signature API you must first upload the document you want signed.

Start Signature Process

curl -X POST https://docubee.app/api/v2/signatures \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "documents": [{ "documentId": "YOUR-DOCUMENT-ID" }], "testMode": true, "expiresOn": "2050-05-15T23:59:59.000Z", "signers": [{ "label": "Alice", "contactMethod": [{ "type": "email", "email": "alice@example.com" }]}, { "label": "Bob", "contactMethod": [{ "type": "link" }], "security": { "password": "MySecretPassword" }}, { "label": "Charlie", "contactMethod": [{ "type": "email", "email": "charlie@example.com" }], "security": { "kba": { "lastName": "Doe", "email": "CharlieDoePersonal@example.com" }}}], "processName": "Quick Sign Process", "onSignaturesFinalized": [{ "type": "email", "email": "response@example.com" }], "tags": { "myTag": "myData" }}'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/signatures', {
  body: JSON.stringify({
    documents: [
      {
        documentId: 'YOUR-DOCUMENT-ID'
      }
    ],
    testMode: true,
    expiresOn: '2050-05-15T23:59:59.000Z',
    signers: [
      {
        label: 'Alice',
        contactMethod: [
          {
            type: 'email',
            email: 'alice@example.com'
          }
        ]
      },
      {
        label: 'Bob',
        contactMethod: [
          {
            type: 'link'
          }
        ],
        security: {
          password: 'MySecretPassword'
        }
      },
      {
        label: 'Charlie',
        contactMethod: [
          {
            type: 'email',
            email: 'charlie@example.com'
          }
        ],
        security: {
          kba: {
            lastName: 'Doe',
            email: 'CharlieDoePersonal@example.com'
          }
        }
      }
    ],
    processName: 'Quick Sign Process',
    onSignaturesFinalized: [
      {
        type: 'email',
        email: 'response@example.com'
      }
    ],
    tags: {
      myTag: 'myData'
    }
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/signatures'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'documents': [
    {
      'documentId': 'YOUR-DOCUMENT-ID'
    }
  ],
  'testMode': True,
  'expiresOn': '2050-05-15T23:59:59.000Z',
  'signers': [
    {
      'label': 'Alice',
      'contactMethod': [
        {
          'type': 'email',
          'email': 'alice@example.com'
        }
      ]
    },
    {
      'label': 'Bob',
      'contactMethod': [
        {
          'type': 'link'
        }
      ],
      'security': {
        'password': 'MySecretPassword'
      }
    },
    {
      'label': 'Charlie',
      'contactMethod': [
        {
          'type': 'email',
          'email': 'charlie@example.com'
        }
      ],
      'security': {
        'kba': {
          'lastName': 'Doe',
          'email': 'CharlieDoePersonal@example.com'
        }
      }
    }
  ],
  'processName': 'Quick Sign Process',
  'onSignaturesFinalized': [
    {
      'type': 'email',
      'email': 'response@example.com'
    }
  ],
  'tags': {
    'myTag': 'myData'
  }
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "processId": "2ce983a7-b51e-435e-a437-ddffa8a78786",
  "tenantId": "fef81022-4bb3-4850-b14f-37ce388e096e",
  "documentId": "ecbe99a2-42e6-494a-b3eb-5cd6718dba48",
  "expiresOn": "2050-05-15T23:59:59.000Z",
  "status": "in-progress",
  "startedOn": "2022-06-01T19:29:22.000Z",
  "startedBy": null,
  "updatedOn": "2022-06-01T19:29:22.000Z",
  "signingOrder": "parallel",
  "testMode": true,
  "processName": "Quick Sign Process",
  "onSignatureFinalized": [
    {
      "type": "email",
      "email": "response@example.com"
    }
  ],
  "signers": [
    {
      "label": "Alice",
      "email": "alice@example.com",
      "status": "in-progress",
      "firstAccessed": null,
      "lastAccessed": null,
      "signedOn": null,
      "signingOrder": null,
      "contactMethod": [
        {
          "type": "email",
          "email": "alice@example.com",
          "status": "success"
        }
      ],
      "security": {
        "kba": false,
        "password": false,
        "twoFactor": false
      }
    },
    {
      "label": "Bob",
      "email": null,
      "status": "in-progress",
      "firstAccessed": null,
      "lastAccessed": null,
      "signedOn": null,
      "signingOrder": null,
      "contactMethod": [
        {
          "type": "link",
          "status": "success",
          "taskUrl": "https://docubee.app/signing/2ce983a7-b51e-435e-a437-ddffa8a78786/signer/95b33004-27b4-4ab9-a1ec-cd6625728124"
        }
      ],
      "security": {
        "kba": false,
        "password": true,
        "twoFactor": false
      }
    },
    {
      "label": "Charlie",
      "email": "charlie@example.com",
      "status": "in-progress",
      "firstAccessed": null,
      "lastAccessed": null,
      "signedOn": null,
      "signingOrder": null,
      "contactMethod": [
        {
          "type": "email",
          "email": "charlie@example.com",
          "status": "success"
        }
      ],
      "security": {
        "kba": true,
        "password": false,
        "twoFactor": false
      }
    }
  ],
  "tags": {
    "myTag": "myData"
  }
}

Start Signature Process

POST /api/v2/signatures

Required Token Permissions

Start Quick Sign

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* documents documentsArray List of all documents to be combined for the signing process
expiresOn string Datetime in UTC to expire the signing process for all signers. Must be a valid ISO 8601 string set to a future date. Example: 2050-05-15T23:59:59.000Z
onSignaturesFinalized finalizedArray List of actions taken when all signers have signed
processName string Optional name for the quick sign process
* signers signersArray List of all signers expected for a given document
signingOrder string, valid values: [ 'parallel', 'serial' ] Specifies the type of signing order. Default is parallel.
supportContact supportContactObject Contact information for signer to communicate with for any questions or issues. Only used when signers[].security.kba is set for a signer.
startedBy string, valid email Email of the user who started the process. This email will receive signer delivery failure notifications when signingOrder: 'serial'
tags object Arbitrary key value pairs of metadata that a user may want to attach to a process. Only string values are supported.
testMode boolean Sets the process in testMode, document and emails are marked with test mode

* denotes required

documentsArray

Array of objects with the following properties. A maximum of 20 documents are allowed.

Key Details Description
* documentId string documentId returned from a call to upload
formDefinitionId string matching ^[a-zA-Z0-9_-]+$ Previously defined formDefinition from fields to use. Default is formDefinition.

* denotes required

finalizedArray

Array of objects with the following properties. A maximum of 20 array entries are allowed.

Key Details Description
* type string, valid values: [ 'email', 'webhook' ] Specifies what type of call back will be used
* email string, only valid for type: 'email', valid email Email to send completed document
method string, only valid for type: 'webhook', valid values: [ 'POST', 'PUT' ] HTTP method to use when sending webhook request. Default is POST
* url string, only valid for type: 'webhook', valid url URL endpoint for webhook request

* denotes required

signersArray

Array of objects with the following properties. A maximum of 6 signers is allowed.

Key Details Description
email string, valid email Email used to identify this signer
* contactMethod contactMethodArray An array of available contact methods for this signer
* label string Label to identify the signer
formRoleId string Defines which formRole this signer is assigned to. Default is formRole${index + 1}.
security securityObject Rules for securing access for the specific signer

* denotes required

supportContactObject

Contact information for signer to communicate with for any questions or issues. The "Organization Name" configured in the general settings is shown to the signer and cannot be overriden here. Only used when signers[].security.kba is set for a signer.

Key Details Description
email string, valid email Email used to communicate with the support contact (Required if phoneNumber is omitted)
* fullName string Name used to refer to the support contact
phoneNumber string, valid phone number The 10-digit US telephone number of the support contact (Required if email is omitted)

* denotes required

contactMethodArray

Array of objects with the following properties.

Key Details Description
* type string, valid values: [ 'email', 'link', 'embed' ] Specifies the type of contact method to use for this signer
email string, only valid for type: 'email', valid email Email to notify this signer

* denotes required

securityObject

Key Details Description
kba kbaObject Configuration for Knowledge Based Authentication (KBA)
password string A password that the signer will be required to provide before accessing the document
twoFactor twoFactorObject Configuration for two-factor authentication

* denotes required

kbaObject

Initial identifying information of the signer to verify. The signer will be prompted to provide more identifying information about themselves and must pass a quiz about their history before being able to see and sign the document. Contact sales for more information about KBA for your organization.

Key Details Description
maxAttempts number, integer from 1 to 3 (inclusive) The number of times a user can attempt the identification quiz before being locked out. The nature of this verification process can make it difficult for even valid users to succeed on their first attempt; therefore, we recommend leaving this as the default. Default is 3.
firstName string The first name of the user to be verified
middleName string The middle name of the user to be verified
* lastName string The last name of the user to be verified
suffix string The suffix of the user to be verified (Sr, Jr, etc)
* email string, valid email The personal email of the user to be verified. This property is used for verification purposes only, not communication, and a work email may not yield a successful result.

* denotes required

twoFactorObject

Key Details Description
* phone string, valid mobile number The 10-digit US mobile telephone number of the recipient
* type string, valid value: 'sms' The supported method for sending the two-factor authorization code

* denotes required

Get Signature Process Status

curl https://docubee.app/api/v2/signatures/:processId/status \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/signatures/:processId/status', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/signatures/:processId/status'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "processId": "88bfdbd3-e69d-4d13-be6a-b555885d75df",
  "tenantId": "ba4e927e-407c-402f-99ac-c33f6d3ed9a3",
  "documentId": "e74bf4a9-6bd4-42eb-b900-a1d7b760942f",
  "expiresOn": null,
  "status": "in-progress",
  "startedOn": "2022-05-31T20:57:14.000Z",
  "updatedOn": "2022-05-31T21:58:15.000Z",
  "signingOrder": "parallel",
  "testMode": false,
  "processName": "Quick Sign Process",
  "onSignaturesFinalized": [
    {
      "type": "email",
      "email": "response@example.com"
    }
  ],
  "signers": [
    {
      "email": "alice@example.com",
      "lastAccessed": null,
      "signedOn": null,
      "status": "in-progress",
      "label": "Alice",
      "contactMethod": [
        {
          "type": "email",
          "email": "alice@example.com",
          "status": "success"
        }
      ]
    },
    {
      "email": null,
      "firstAccessed": "2022-05-31T21:57:56.000Z",
      "lastAccessed": "2022-05-31T21:57:57.000Z",
      "signedOn": "2022-05-31T21:58:15.000Z",
      "status": "complete",
      "label": "Bob",
      "contactMethod": [
        {
          "type": "link",
          "status": "success",
          "taskUrl": "https://docubee.app/signing/:processId/signer/:taskId"
        }
      ]
    }
  ],
  "startedBy": null,
  "tags": {}
}

Get Signature Process Status

GET /api/v2/signatures/:processId/status

Required Token Permissions

Get Quick Sign process data

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

List Signature Processes

curl https://docubee.app/api/v2/signatures \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/signatures', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  }
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/signatures'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}

response = requests.get(url=url, headers=headers)
print(response.json())

The above request returns a JSON object structured like this:

{
  "records": [
    {
      "processId": "b68a2df5-04c8-4a85-9061-b3da20b901a1",
      "tenantId": "8efa8474-85b0-4de9-b3ac-04f54f2f8463",
      "documentId": "57b7c041-5560-4083-b2c6-d27afbbed717",
      "status": "in-progress",
      "startedOn": "2022-10-04T15:50:51.000Z",
      "startedBy": null,
      "updatedOn": "2022-10-04T15:50:51.000Z",
      "signingOrder": "parallel",
      "testMode": false,
      "processName": "Quick Sign Process",
      "onSignaturesFinalized": [
        {
          "type": "email",
          "email": "test@email.com"
        }
      ],
      "key": "b68a2df5-04c8-4a85-9061-b3da20b901a1",
      "signers": [
        {
          "label": "second Signer",
          "email": "signer@email.com",
          "status": "in-progress",
          "firstAccessed": null,
          "lastAccessed": null,
          "signedOn": null,
          "signingOrder": null,
          "contactMethod": [
            {
              "type": "email",
              "email": "signer@email.com",
              "status": "success"
            }
          ],
          "security": {
            "password": false
          }
        }
      ],
      "tags": {}
    },
    {...}
  ],
  "next": "ac875474"
}

List Signature Processes

GET /api/v2/signatures

Required Token Permissions

List Quick Sign processes

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Query Parameters

Parameter Description
cursor A value returned as the next property in a previous response. Used to fetch subsequent pages of results. Default is null.
source A value that filters the processes by the source they were started from. Options are quick-sign, documents, and api. The quick-sign option returns processes started via Quick Sign, documents returns processes started via the My Documents section, and api returns processes started via the signature API. Default is api.

Pagination

This endpoint returns up to 50 processes per request. If there are more additional records available, the response will contain an additional next property, which can be passed in a subsequent request as cursor. When retrieving the last instances, there will be no next property.

Delete Signature Process

curl -X DELETE https://docubee.app/api/v2/signatures/:processId \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/signatures/:processId', {
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN'
  },
  method: 'DELETE'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/signatures/:processId'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN'
}

response = requests.delete(url=url, headers=headers)
print(response.json())

Delete Signature Process

DELETE /api/v2/signatures/:processId

Required Token Permissions

Delete Quick Sign process

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Replacements API

The Replacement API allows replacing templated strings in a .docx document with data. This adds data inline in the document and can be used as a precursor to signing. Templated strings must be wrapped in {% and %} anchors in the document (i.e. {%firstName%}).

To get started with the Replacements API you must first upload the document you want signed.

Configuring Your Document

Because the Replacement API works in-place within files, templated strings can sit alongside standard content within a document.

Hello {%applicant-name%}, Thank you for your interest in {%company-name%}!

Document Sections

Define a section in your document by including an opening template tag {%#section-name%} and a corresponding closing tag {%/section-name%}. This section can be conditionally included (or excluded) by passing a boolean in the API or can be looped over to repeat sections in the document by passing an array. Template data can also be included within sections and will be templated accordingly. Sections can also be nested.

In the following document snippet we define a section named include-dependents that will be conditionally included. This will use the top level applicant-name and a looped section named dependent-information containing the name and age of each dependent.

{%#include-dependents%} Dependent information for {%applicant-name%}: {%#dependent-information%} Name: {%name%}, Age: {%age%} {%/dependent-information%} {%/include-dependents%}

Here's the corresponding API snippet for the previous document snippet:

{ 'applicant-name': 'Alice Doe', 'include-dependents': true, 'dependent-information': [ { 'name': 'Bob Doe', 'age': '42' }, { 'name': 'Charlie Doe', 'age': '16' } ] }

Which results in the following document snippet:

Dependent information for Alice Doe: Name: Bob Doe, Age: 42 Name: Charlie Doe, Age: 16

Inline Replace Existing Document

curl -X POST https://docubee.app/api/v2/contentReplacers \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "documentId": "d48dffbb-8031-4eef-a8f5-794790dd998d", "replacements": { "firstName": "Alice", "lastName": "Doe", "dateOfBirth": "2000-04-01", "employeeId": "#8675309" }}'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/contentReplacers', {
  body: JSON.stringify({
    documentId: 'd48dffbb-8031-4eef-a8f5-794790dd998d',
    replacements: {
      firstName: 'Alice',
      lastName: 'Doe',
      dateOfBirth: '2000-04-01',
      employeeId: '#8675309'
    }
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/contentReplacers'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'documentId': 'd48dffbb-8031-4eef-a8f5-794790dd998d',
  'replacements': {
    'firstName': 'Alice',
    'lastName': 'Doe',
    'dateOfBirth': '2000-04-01',
    'employeeId': '#8675309'
  }
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "documentId": "9e732369-29a1-4d71-8ddd-7fde3a909acd"
}

Replace templated anchor strings in a document with predetermined strings.

Inline Replace Document

POST /api/v2/contentReplacers

Required Token Permissions

Document Content Replacer

Headers

Header Type Description
* Authorization string Your workspace access token.
collection string, valid values: [ 'default', 'my-documents' ] The document collection to store this document
filename string Custom filename
path string File path within the collection (Required if the collection is 'my-documents')

* denotes required

Body

Key Details Description
* documentId The ID of the .docx document to set fields on
* replacements Object of key and replacement-value pairs; key must start with a letter and contain only 'a-z', 'A-Z', '0-9', '_', '-' Object of keys defining anchor strings on the document and corresponding value strings defining the replacement to occur.

* denotes required

Replacement Value

Value Type Details Description
string Replaces the corresponding replacements key with the provided string value
boolean Indicates whether or not a given section denoted by the corresponding replacements key should be included
array Object of key and replacement-value pairs; key must start with a letter and contain only 'a-z', 'A-Z', '0-9', '_', '-' Indicates that a given section denoted by the corresponding replacements key should be looped over

Embedded Interfaces

Each embedded option makes a similar API call to the same path differing only in the data object. Example calls are provided in each of the embed page sections along with the relevant options.

Interacting with the embedded instance

Docubee will emit events to the parent using postMessage. You can listen for the specific changes in state to trigger navigation, content, or removal of the iframe from the page by using addEventListener.

The following example shows how to listen for events that come from the iframe:

window.addEventListener('message', (message) => { if (!message.origin.includes('docubee.app')) { return; } const { details, event } = JSON.parse(message.data); if (event !== 'SIGNING_STATUS') { return; } // details.status can be used to trigger changes }, false);

The specific details and event for each embedded page are documented accordingly.

Embedded Field Placement

curl -X POST https://docubee.app/api/v2/embed \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "data": { "documentId": "ec7ab7db-a063-4379-b48f-aa65589c1d83", "formDefinitionId": "my_form" }, "domain": "https://secure.mydomain.com:*", "page": "fieldPlacement" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/embed', {
  body: JSON.stringify({
    data: {
      documentId: 'ec7ab7db-a063-4379-b48f-aa65589c1d83',
      formDefinitionId: 'my_form'
    },
    domain: 'https://secure.mydomain.com:*',
    page: 'fieldPlacement'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/embed'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'data': {
    'documentId': 'ec7ab7db-a063-4379-b48f-aa65589c1d83',
    'formDefinitionId': 'my_form'
  },
  'domain': 'https://secure.mydomain.com:*',
  'page': 'fieldPlacement'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "url": "https://docubee.app/embed/ui/c1d5a3fb-d84e-4592-bf64-ef645f03f18e"
}

Before embedding a ui for placing fields you must first get a documentId by uploading a document using the Upload Documents API.

Review our Help Center article for more information.

Embed Field Placement

POST /api/v2/embed

Required Token Permissions

Generate Embedded UI URL

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* data dataObject The config options for the embedded page.
* domain string The whitelisted domain authorized to host the embedded content
* page string, valid value [ 'fieldPlacement' ] Indicates the type of embedded page

* denotes required

dataObject

Key Details Description
* documentId string documentId returned from a call to the Upload Documents API. Identifies which document to draw the fields upon.
formDefinitionId string Defines a named formDefinition that can be used in the start signature process.

* denotes required

Embedded Signing

curl -X POST https://docubee.app/api/v2/embed \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "data": { "processId": "e5acefca-4f1c-459b-b484-2704a264ab27", "signerId": "a93e6bf4-17de-4f65-8cce-f1b44fba303c" }, "domain": "https://secure.mydomain.com:*", "page": "signing" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/embed', {
  body: JSON.stringify({
    data: {
      processId: 'e5acefca-4f1c-459b-b484-2704a264ab27',
      signerId: 'a93e6bf4-17de-4f65-8cce-f1b44fba303c'
    },
    domain: 'https://secure.mydomain.com:*',
    page: 'signing'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/embed'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'data': {
    'processId': 'e5acefca-4f1c-459b-b484-2704a264ab27',
    'signerId': 'a93e6bf4-17de-4f65-8cce-f1b44fba303c'
  },
  'domain': 'https://secure.mydomain.com:*',
  'page': 'signing'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "url": "https://docubee.app/embed/ui/c1d5a3fb-d84e-4592-bf64-ef645f03f18e"
}

Before embedding a signing process you must first get a processId and signerId by starting a signing process using the Signature API.

Review our Help Center article for more information.

Embed Signature Process

POST /api/v2/embed

Required Token Permissions

Generate Embedded UI URL

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* data dataObject The config options for the embedded page.
* domain string The whitelisted domain authorized to host the embedded content
* page string, valid value [ 'signing' ] Indicates the type of embedded page

* denotes required

dataObject

Key Details Description
* processId string processId returned from a call to the Signature API. Identifies which process to embed.
* signerId string signerId returned from a call to the Signature API. Identifies which signer step to embed.

* denotes required

postMessage Events Emitted to the Parent

Describes the event your application can listen for to interact with Docubee.

Key Details Description
details object Object containing the specific event details.
details.processId string The current embedded signing process.
details.signerId string The active signer of the embedded signing process.
details.status string Indicates the current status of the embedded page.
event string, value of SIGNING_STATUS The current event that triggered the postMessage.

Embedded Web Forms

curl -X POST https://docubee.app/api/v2/embed \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "data": { "formId": "6726e639-f596-456f-ae88-6f0093816cd2" }, "domain": "https://secure.mydomain.com:*", "page": "webForm" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/embed', {
  body: JSON.stringify({
    data: {
      formId: '6726e639-f596-456f-ae88-6f0093816cd2'
    },
    domain: 'https://secure.mydomain.com:*',
    page: 'webForm'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/embed'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'data': {
    'formId': '6726e639-f596-456f-ae88-6f0093816cd2'
  },
  'domain': 'https://secure.mydomain.com:*',
  'page': 'webForm'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "url": "https://docubee.app/embed/ui/c1d5a3fb-d84e-4592-bf64-ef645f03f18e"
}

Before you begin you must first create and publish a form and get the formId from the url (the formId is the guid at the end of the published URL).

Review our Help Center article for more information.

Embed Signature Process

POST /api/v2/embed

Required Token Permissions

Generate Embedded UI URL

Complete Standalone Web Forms

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* data dataObject The config options for the embedded page.
* domain string The whitelisted domain authorized to host the embedded content
* page string, valid value [ 'webForm' ] Indicates the type of embedded page

* denotes required

dataObject

Key Details Description
* formId string formId extracted from a published Form URL. Indicates which form to embedd.
hideActions boolean Indicates whether to hide Docubee's "Submit" button
submitToServer boolean Indicates whether to write results to Docubee or to propogate results to the parent app in a postMessage
prefill object Object containing keys that match the Property Name of questions on the form. Will will the matching question with the provided value.

* denotes required

postMessage Events Emitted to the Parent

Describes the event your application can listen for to interact with Docubee.

Key Details Description
details object Object containing the specific event details.
details.error object Object containing details in case of an error.
details.fields object Object containing the data of the current form state.
details.formId string Indicates which embedded form triggered the event.
details.height string Height of the current form in pixels.
details.numberOfInvalidFields number How many fields have values that failed validation.
details.timeoutInMs number How long in milliseconds there is to prefill data.
event string, valid responses [ 'FORM_READY', 'READY_FOR_DATA', 'EVENT_ERROR', 'CONTENT_HEIGHT', 'FORM_SUBMITTED' ] The current event that triggered the postMessage.

Embedded Workflow Start Page

curl -X POST https://docubee.app/api/v2/embed \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "data": { "templateId": "f5315245-23d6-423d-b81a-8741bc33a9db" }, "domain": "https://secure.mydomain.com:*", "page": "workflowStart" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/embed', {
  body: JSON.stringify({
    data: {
      templateId: 'f5315245-23d6-423d-b81a-8741bc33a9db'
    },
    domain: 'https://secure.mydomain.com:*',
    page: 'workflowStart'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/embed'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'data': {
    'templateId': 'f5315245-23d6-423d-b81a-8741bc33a9db'
  },
  'domain': 'https://secure.mydomain.com:*',
  'page': 'workflowStart'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "url": "https://docubee.app/embed/ui/c1d5a3fb-d84e-4592-bf64-ef645f03f18e"
}

Before embedding a workflow start page you must first get a templateId by calling the List Workflows API.

Review our Help Center article for more information.

Embed Signature Process

POST /api/v2/embed

Required Token Permissions

Generate Embedded UI URL

Start workflow instances

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* data dataObject The config options for the embedded page.
* domain string The whitelisted domain authorized to host the embedded content
* page string, valid value [ 'workflowStart' ] Indicates the type of embedded page

* denotes required

dataObject

Key Details Description
* templateId string templateId returned from a call to List Workflows. Identifies which workflow to embed.

* denotes required

postMessage Events Emitted to the Parent

Describes the event your application can listen for to interact with Docubee.

Key Details Description
details object Object containing the specific event details.
details.embedUrl string The URL of the workflow runtime. For use in redirecting a user to Docubee to complete the workflow.
details.instanceId string The specific instance that was started from the template. For use in continuing the Workflow Runtime in an embedded environment.
details.originatorToken string Encoded information about the workflow.
event string, value of WORKFLOW_STARTED The current event that triggered the postMessage.

Embedded Workflow Runtime

curl -X POST https://docubee.app/api/v2/embed \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "data": { "instanceId": "ea1f94e8-cf4a-4fa8-91ee-8212196aef95", "participant": "participant@example.com" }, "domain": "https://secure.mydomain.com:*", "page": "workflowRuntime" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/embed', {
  body: JSON.stringify({
    data: {
      instanceId: 'ea1f94e8-cf4a-4fa8-91ee-8212196aef95',
      participant: 'participant@example.com'
    },
    domain: 'https://secure.mydomain.com:*',
    page: 'workflowRuntime'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/embed'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'data': {
    'instanceId': 'ea1f94e8-cf4a-4fa8-91ee-8212196aef95',
    'participant': 'participant@example.com'
  },
  'domain': 'https://secure.mydomain.com:*',
  'page': 'workflowRuntime'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "url": "https://docubee.app/embed/ui/c1d5a3fb-d84e-4592-bf64-ef645f03f18e"
}

Before embedding a workflow page you must first get an instanceId by listening to an event fired from the Embedded Workflow Start Page API or by calling the Start Workflow API.

Review our Help Center article for more information.

Embed Signature Process

POST /api/v2/embed

Required Token Permissions

Generate Embedded UI URL

Start workflow instances

Headers

Header Type Description
Authorization string Your workspace access token. (Required)

Body

Key Details Description
* data dataObject The config options for the embedded page.
* domain string The whitelisted domain authorized to host the embedded content
* page string, valid value [ 'workflowRuntime' ] Indicates the type of embedded page

* denotes required

dataObject

Key Details Description
* instanceId string instanceId returned from an event fired from the Embedded Workflow Start Page API or by calling the Start Workflow API. Identifies which workflow instance to embed.
participant string; valid email or 'anonymous' Identifies which workflow user's task to embed.

* denotes required

postMessage Events Emitted to the Parent

Describes the event your application can listen for to interact with Docubee.

Key Details Description
details object Object containing the specific event details.
details.error object Object containing details in case of an error.
details.instanceId string The instance of the embedded workflow.
event string, valid responses FATAL_ERROR, WORKFLOW_CANCELED, WORKFLOW_COMPLETE, NO_TASKS_AVAILABLE The current event that triggered the postMessage.

Other Endpoints

Generate a Short URL

curl -X POST https://docubee.app/api/v2/urls \
  -H 'Authorization: WORKSPACE-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "targetUrl": "https://docubee.app/some/path" }'

const fetch = require('node-fetch');

const response = await fetch('https://docubee.app/api/v2/urls', {
  body: JSON.stringify({
    targetUrl: 'https://docubee.app/some/path'
  }),
  headers: {
    Authorization: 'WORKSPACE-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  method: 'POST'
});

const res = await response.json();

import requests

url = 'https://docubee.app/api/v2/urls'
headers = {
  'Authorization': 'WORKSPACE-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}
json = {
  'targetUrl': 'https://docubee.app/some/path'
}

response = requests.post(url=url, headers=headers, json=json)
print(response.json())

The above request returns a JSON object structured like this:

{
  "expires": "2022-05-31T21:58:15.000Z",
  "url": "https://docubee.app/k/FhqWhgADsh"
}

Generates a temporary short URL for the given full Docubee URL

Generate a Short URL

POST /api/v2/urls

Required Token Permissions

Create Short URL

Headers

Header Type Description
* Authorization string Your workspace access token.

* denotes required

Body

Key Details Description
* targetUrl url The full URL that must begin with https://docubee.app/

* denotes required

Legal

Docubee, an Accusoft property. Copyright © 2016-. Accusoft Corporation. All rights reserved.

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Accusoft® Corporation.

This manual and the software described in it are both products of the USA.

Accusoft Corporation
4001 North Riverside Drive
Tampa, FL 33603
Sales: 813-875-7575
www.accusoft.com

Accusoft Trademarks

Visit our website for a complete list of trademarks (™) and registered marks (®) of Accusoft Corporation.

Accusoft and/or its agents use these marks and brand names in connection with its goods and/or services, in the United States and other countries.

Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent.

Python is a registered trademark of the Python Software Foundation.

All other product and brand names are the property of their respective owners.

cURL Node.js Python