Create a task

In this guide we'll demonstrate how to use the API to create a task from a file that contains one or more documents to be processed.

If the files you want to process are in a folder on a Windows or Linux file system, we recommend using the Aluma File System Agent application instead of using the API. The File System Agent can monitor a folder and create tasks for files in the folder automatically.

This guide assumes you have already created a project in your account by uploading a project file or installing the demo project using the admin portal.

1. Get a project ID

To create a task you will need the ID of the project you want to use to process the file. You can get this by going to the Projects page in the Aluma app, clicking on the project and finding its ID property.

2. Create a task from the file

The file to be processed must be in PDF or TIFF format. Files not in this format will be accepted, but will cause processing of the task to fail.

To create a task, make a Create Task request with:

• The project_id query parameter set to the project ID.
• The request body containing the binary contents of the file to be processed.
• The Content-Type header set to the MIME type of the file (either application/pdf or image/tiff).
• The X-Aluma-Tags header set to task_name=<task name> where <task name> is a name that will be displayed to any validation user working on the task and will help you link this task back to its source in your system, for example a record ID, filename or case number.

The following tags can also be set in order to pass metadata relating to the file, which can be used in your project's automation:

• file_name, e.g. file_name=001.pdf
• file_path, e.g. file_path=C:\inbox
• file_created_time, e.g. file_created_time=1711958908 (a unix timestamp)

To set more than one tag, separate them using an & character:

POST /tasks?project_id=ZbfzIZorTFOV60GX58YUuQ
Content-Type: application/pdf
X-Aluma-Tags: task_name=AB3947853&file_name=00001.pdf&file_path=C:\inbox&file_created_time=1711958908

Body: File contents

A successful request will return a 202 Accepted response that contains the properties of the task:

{
  "id": "SWdh86taQhKwwpY0HUKD7Q",
  "name": "AB3947853",
  "file_collection_id": "hZ7GkxSHSRmk9ibpio_yOQ",
  "project_id": "ZbfzIZorTFOV60GX58YUuQ",
  "project_name": "ACME Medical Records",
  "created_at": "2024-03-25T16:37:08Z",
  "state": "queued"
}

Once created, a task is processed asynchronously by Aluma and is queued automatically for validation by a user (if necessary) and then for export.

You can create as many tasks as you like and Aluma will process them as fast as possible. If you created a large number of tasks in a short period of time you may see tasks remain in the queued state for a little longer until there is free processing capacity.

To retrieve the task's data once it has been processed, you can either use the API or the Aluma File System Agent. The Export Data guide describes how to use the API to export the data to your system.

A task has a state that indicates which stage of processing the task has reached. You can get the current state of a task using a Get Task or List Tasks request. The possible values ofstate are:

When a task reaches one of the completed, failed, timed-out or canceled states the original file and all related data are deleted from the Aluma service.

The task remains available for around 72 hours in its final state so your client code can check its state if necessary.