NAV
cURL Node.js Python
OnTask API Reference

Overview

OnTask gives you an easy-to-use, flexible, and affordable cloud-based platform to take control of all your documents and forms. Your reusable templates 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 OnTask

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 group that owns the workflow template(s) or other resources you are working with.

Before you begin, you will need to gain access to the API. You can either sign up for an enterprise account to do so, or try the API as part of your 14-day free trial.

To sign up for an enterprise plan that includes API access, see our pricing page. If you are currently using a 14-day free trail and would like to test the API endpoint, contact us today or reach out to support@ontask.io to get temporary access.

  1. Signup for an OnTask enterprise account.
  2. Create a workflow.
  3. Use the OnTask user interface or the API to upload documents and start workflows.

Base URL

The base URL for the OnTask API is https://app.ontask.io/

Postman Collection

You can download the OnTask API Postman collection here:

Authentication

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

curl "https://app.ontask.io/api/v2/fake/example/route" \
  -H "Authorization: YOUR-GROUP-ACCESS-TOKEN"
const fetch = require('node-fetch');

const response = await fetch('https://app.ontask.io/api/v2/fake/example/route', {
  headers: {
    Authorization: 'YOUR-GROUP-ACCESS-TOKEN'
  }
})
import requests

url = 'https://app.ontask.io/api/v2/fake/example/route'
headers = {
  'Authorization': 'YOUR-GROUP-ACCESS-TOKEN'
}
response = requests.get(url=url, headers=headers, data=data)

Make sure to replace YOUR-GROUP-ACCESS-TOKEN with your group access token.

OnTask requires a valid group access token to allow access to the API.

Generate an Access Token

  1. Log in to your OnTask account by visiting https://app.ontask.io/login.
  2. Click Organization Settings.
  3. In the left sidebar, select the group to which you want to create an access token for.
  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.

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

Authorization: YOUR-GROUP-ACCESS-TOKEN

Documents

Download

curl -X GET https://app.ontask.io/api/v2/documents/:documentId \
  -H 'Authorization: GROUP-ACCESS-TOKEN' \
  -o myfile.extension
const fs = require('fs');
const fetch = require('node-fetch');

const response = await fetch(`https://app.ontask.io/api/v2/documents/:documentId`, {
  headers: {
    Authorization: 'GROUP-ACCESS-TOKEN'
  },
  method: 'GET'
});

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

url = 'https://app.ontask.io/api/v2/documents/:documentId'
headers = {
  'Authorization': 'GROUP-ACCESS-TOKEN'
}

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

Response:

<<file bytes>>

Download a document from OnTask.

Download a Document

GET /api/v2/documents/:documentId

Required Token Permissions

Get documents

Headers

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

Upload

curl -X POST https://app.ontask.io/api/v2/documents \
  -H 'Authorization: GROUP-ACCESS-TOKEN' \
  -H 'Content-Type: application/pdf' \
  --data-binary "@path/to/file.pdf"
const fs = require('fs');
const fetch = require('node-fetch');

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

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

const { documentId } = await response.json();
import requests
import json

url = 'https://app.ontask.io/api/v2/documents'
headers = {
  'Authorization': 'GROUP-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 JSON object structured like this:

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

Upload a new document to OnTask 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 group access token. (Required)
Content-Type string The MIME type of the supplied document. (Required)
filename string Custom filename (Optional)

Body

A binary document.

Fields

curl -X PUT https://app.ontask.io/api/v2/documents/:documentId/fields \
  -H 'Authorization: GROUP-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "fields": [{ "anchorString": "AnchorText", "name": "TestDisplayName", "removeAnchorString": true, "required": true, "type": "signature" }] }'
const fetch = require('node-fetch');

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

const { documentId } = await response.json();
import requests
import json

url = 'https://app.ontask.io/api/v2/documents/:documentId/fields'
headers = {
  'Authorization': 'GROUP-ACCESS-TOKEN'
  'Content-Type': 'application/json'
}
json={ "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 JSON object structured like this:

{
  "documentId": "e0e513ec-7086-4718-b4da-f0d5e2abe25b"
}

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 group access token. (Required)

Body

An array of field objects that specify where to set fields on the document.

Field Object

Key Details Description
anchorString string, required, must be unique The string in the document to search for and apply the field to.
name string, required Label the person filling out the form will see for this field.
type string, required, valid values: [ "checkbox", "date", "initials", "signature", "text" ] Label the person filling out the form will see for this field.
height number, optional The height of the field. See table below for default values. Units are in points (1/72 of an inch)
width number, optional The width of the field. See table below for default values. Units are in points (1/72 of an inch)
xOffset number, optional 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, optional 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, optional Marks the field as required for the person filling out the form. Default is false.
propertyName string, optional, only valid for types [ "checkbox", "date", "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, optional When set this will redact the anchor string from the document. Default is false.

Field Object Defaults

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

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

Workflow Templates

List

curl https://app.ontask.io/api/v2/workflowTemplates \
  -H 'Authorization: GROUP-ACCESS-TOKEN'
const fetch = require('node-fetch');

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

const templates = await response.json();
import requests
import json

url = 'https://app.ontask.io/api/v2/workflowTemplates'
headers = {
  'Authorization': 'GROUP-ACCESS-TOKEN'
}

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

The above request returns JSON array structured like this:

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

This endpoint retrieves a list of workflow templates in the group the access token belongs to.

List Workflow Templates

GET /api/v2/workflowTemplates

Required Token Permissions

List workflow templates

Headers

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

Create New

curl -X POST https://app.ontask.io/api/v2/workflowTemplates \
  -H 'Authorization: GROUP-ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{ "templateName": "My Workflow Template" }'
const fetch = require('node-fetch');

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

const { templateId } = await response.json();
import requests

url = 'https://app.ontask.io/api/v2/workflowTemplates'
headers = {
  'Authorization': 'GROUP-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 JSON object structured like this:

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

Create a new, empty workflow template.

Create Template

POST /api/v2/workflowTemplates

Required Token Permissions

Manage templates

Headers

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

Body

Property Type Description
templateName string The title of this workflow template. Default is Untitled Template.

Export

curl https://app.ontask.io/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: GROUP-ACCESS-TOKEN'
const fs = require('fs');
const fetch = require('node-fetch');

const response = await fetch(`https://app.ontask.io/api/v2/workflowTemplates/:templateId`, {
  headers: {
    Authorization: 'GROUP-ACCESS-TOKEN'
  },
  method: 'GET'
});

const buffer = await response.buffer();
fs.writeFileSync('/path/to/export.otw', buffer);
import requests

url = 'https://app.ontask.io/api/v2/workflowTemplates/:templateId'
headers = {
  'Authorization': 'GROUP-ACCESS-TOKEN'
}

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

Response:

<<file bytes>>

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

Export Template

GET /api/v2/workflowTemplates/:templateId

Required Token Permissions

Manage templates

Headers

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

Import

curl -X POST https://app.ontask.io/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: GROUP-ACCESS-TOKEN' \
  -H 'Content-Type: application/ontask' \
  --data-binary "@path/to/file.otw"
const fs = require('fs');
const fetch = require('node-fetch');

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

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

await response.json();
import requests
import json

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

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

The above request returns JSON object structured like this:

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

Import a previously exported OTW (OnTask Workflow) description. A valid file can be retrieved from the Export Template API or from the OnTask workflow builder UI.

Import Template

PUT /api/v2/workflowTemplates/:templateId

Required Token Permissions

Manage templates

Headers

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

Query Parameters

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

Body

A valid OTW export file

Get Start Form

curl https://app.ontask.io/api/v2/workflowTemplates/:templateId/startForm
const fetch = require('node-fetch');

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

const startForm = await response.json();
import requests
import json

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

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

The above request returns JSON object structured like this:

{
  "workflowOwner": "...",
  "workflowOwnerData": {
    "owningOrgTenantId": "...",
    "owningOrgName": "API Example",
    "owningOrgUserId": "...",
    "owningGroupTenantId": "...",
    "owningGroupName": "My Example Group",
    "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 templates start form.

Get Template Start Form Data

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

URL Parameters

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

Start Workflow

curl -X POST https://app.ontask.io/api/v2/workflowTemplates/:templateId \
  -H 'Authorization: GROUP-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://app.ontask.io/api/v2/workflowTemplates/:templateId', {
  headers: {
    Authorization: 'GROUP-ACCESS-TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    File_Upload: 'VALID_DOCUMENT_ID',
    Sender_Name: 'Steve'
  }),
  method: 'POST'
});

const workflowInstanceData = await response.json();
import requests
import json

url = 'https://app.ontask.io/api/v2/workflowTemplates/:templateId'
headers = {
  'Authorization': 'GROUP-ACCESS-TOKEN'
}
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 JSON object structured like this:

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

This endpoint starts a workflow template.

Start Workflow Template

POST /api/v2/workflowTemplates/:templateId

Required Token Permissions

Start workflow instances

Headers

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

URL Parameters

Parameter Description
templateId The ID of the workflow template (Can be found from the LIST templates 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://app.ontask.io/api/v2/workflowTemplates/:templateId/instances \
  -H 'Authorization: GROUP-ACCESS-TOKEN'
const fetch = require('node-fetch');

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

const { instances, next } = await response.json();
import requests
import json

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

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

The above request returns 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 template.

List Instances

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

Required Token Permissions

Get instance data

Headers

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

URL Parameters

Parameter Description
templateId The ID of the workflow template (Can be found from the LIST templates 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.
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 Properties

curl https://app.ontask.io/api/v2/instances/:instanceId/properties \
  -H 'Authorization: GROUP-ACCESS-TOKEN'
const fetch = require('node-fetch');

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

const { properties } = await response.json();
import requests
import json

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

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

The above request returns 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 group access token. (Required)

List Documents

curl https://app.ontask.io/api/v2/instances/:instanceId/documents \
  -H 'Authorization: GROUP-ACCESS-TOKEN'
const fetch = require('node-fetch');

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

const { documents } = await response.json();
import requests
import json

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

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

The above request returns 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 group access token. (Required)

Legal

OnTask, an Accusoft property. Copyright © 2016-2020. 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.