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.
- Sign up for an Docubee account.
- Create a workflow.
- 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
- Log in to your Docubee account by visiting https://docubee.app/login.
- Click the settings gear icon at the bottom of the left navigation bar.
- In the left sidebar, select the workspace for which you want to create an access token.
- Expand the ACCESS TOKENS section.
- Choose a name for this API connection.
- Choose the permission level for this token. Required token permissions are listed for each API route below.
- Click GENERATE TOKEN.
- 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:
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 |
* | 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 | |
---|---|---|---|
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 | |
---|---|---|---|
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 |
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) | |
* | 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
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
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
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
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
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
Copyright
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.