Overview

The Aluma Tasks API is an HTTP API that enables you to submit files to the Aluma service to be processed and export the resulting data and associated files.

Using the Tasks API you can:

Create tasks from PDF or TIFF files containing either a single document or multiple documents to be automatically separated.
Export data for each processed document.
Manage projects that define how each task should be processed.

You can use the API to do both task creation and data export, or use the Aluma File System Agent to do one of these. For example, you can use the File System Agent to monitor a folder and create tasks for each file in the folder but use the API to export data to your own Document Management system or database.

Where tasks require review by a human, your users can use the Aluma validation portal to do so. You can use the API to build a custom validation user interface if this is valuable to you. For example, you can build an application that runs on a multi-function device that scans a document, submits it to Aluma for processing and allows the user to review and complete the data directly on the device.

Concepts

Projects

An Aluma Project defines how a task should be processed, including (but not limited to):

Whether files are expected to include multiple documents that should be separated automatically.
If multiple document types are expected, with different fields, how these document types should be identified.
The fields to be captured for each document type and the configuration that defines how these should be captured.
Any validations and validation portal settings relevant to the fields.
The naming, format and content of document and data output files that are required.

The Aluma team will create a project for you and provide this as a file with an .alproj extension. You can upload this to your account in the Aluma app, or using an Upload Project API request.

Tasks

A Task represents the processing of a single file through the processing workflow using a project.

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

A task has a state that indicates which stage of processing the task has reached. The possible values ofstate are:

State	Description
`queued`	The task is queued for processing.
`running`	The task is being processed.
`pending:start_client_action`	The task is waiting for validation or export. The `client_action` property specifies which one.
`pending:complete_client_action`	The task is being validated or exported. The `client_action` property specifies which one.
`completed`	Final state. The task was successfully processed and there is no further work to do. The original file and all related data have been deleted from the Aluma service.
`failed`	Final state. There was an unrecoverable error during the processing of the task. The original file and all related data have been deleted from the Aluma service.
`timed-out`	Final state. The processing of the task was not completed within the period specified in the project. The original file and all related data have been deleted from the Aluma service.
`canceled`	Final state. The processing of the task was canceled, and no further processing will take place. The original file and all related data have been deleted from the Aluma service.

You can check the state of a Task using a Get Task or List Tasks request.

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.