Upload and Extract (v2)

Upload documents and run workflows with more optionality

V2 of the Sypht API has been designed to offer users greater flexibility and more functionality by decoupling the file upload and workflow requests, allowing users to run one or more workflows on a single document.

Getting Started

Making a prediction to extract data via the Sypht API has two basic steps:

1. Upload a document

2. Invoke a workflow

3. Retrieve the results (optional - if the workflow has been invoked asynchronously)

File upload requests return a fileId which will be used to refer to that file in subsequent requests to invoke workflows or retrieve results.

Workflow requests are asynchronous and work by placing the workflow request into a queue for later processing. After invoking the workflow you can poll the results endpoint and will receive results once the workflow is complete and the results have been finalised.

1. Upload file: POST /fileupload/v2/multipart

This guide will demonstrate how to make uploads and predictions using API calls in Postman. Please see our provided clients to do this programmatically.

Request headers

• Content-Type = multipart/form-data

• Accept= application/json

• Authorization= Bearer {{access token}}

Request Payload

file: binary of a PDF, PNG or JPG to extract fields from. Maximum file size supported is 20Mb with maximum page limit of 16. Limits can be adjusted on request.

Response

{
    "id": "1bed7458-13f8-4152-810f-81e5274312e4",
    "fileId": "1bed7458-13f8-4152-810f-81e5274312e4",
    "uploadedAt": "2023-03-30T03:09:22.361Z",
    "status": "RECEIVED"
}

The fileId in the response is the unique identifier used for the uploaded document which will be used to identify the document in future api requests.

2. Invoke Workflow: POST /workflows/<workflowId>/jobs

The invoke workflow endpoint places your workflow request onto a queue for later processing. The results will be available via the results endpoint in a matter of seconds.

Request headers

• Content-Type = application/json

• Accept= application/json

• Authorization= Bearer {{access token}}

Parameters

workflowId: the id of the workflow, can be one of the default sypht workflows or a custom workflow we have tailored to your use case. Default workflow ids are sypht.ingest, sypht.extract, sypht.split or sypht.validate

Request body

The request body depends on the workflow being invoked. Some workflows will require their own workflow specific inputs inputs, below is an example of the request body for the sypht.extract workflow. Further information is in later sections regarding v2 workflows.

{
    "inputs":{
        "file_id":":73a958f8-61e9-4c44-82bc-05ab7db95de2",
        "product_ids":["ndis-claims:2"]
    }
}

Response body

{
    "job": {
        "id": "", //uuid
        "company_id": "", //uuid
        "created": "2023-03-28T22:36:03.911887",
        "workflow_id": "", //worflowId 
        "inputs": {
            ...
            //key-value pairs of workflow inputs
        },
        "settings": {
            // key-value pair of your sypht settings
            ...
        },
        "usage": null,
        "file_id": "",
        "status": "new",
        "version": 3
    },
    "message_id": "" //uuid
}

2. Fetch results: GET /result/final/<fileId>

After submitting a /fileupload/ request, the extraction request is queued asynchronously and results can be retrieved via a GET request to /results/<fileId> with the fileId found in the response.

For the above example, a GET request to api.sypht.com/result/final/f15ead36-dd97-4e1e-8db8-cad0fb9f5e07

{
    "fileId": "f15ead36-dd97-4e1e-8db8-cad0fb9f5e07",
    "status": "FINALISED",
    "results": {
        "timestamp": "2020-11-02T01:15:10.535Z",
        "fields": [
            {
                "name": "issuer.businessNo",
                "value": "13313135031",
                "confidence": 0.9869603735738959,
                "boundingBox": {
                    "pageNum": 1,
                    "topLeft": {
                        "x": 0.8033333333333334,
                        "y": 0.12333333333333334
                    },
                    "bottomRight": {
                        "x": 0.92152943176447052,
                        "y": 0.17342135454545454
                    },
                    "tokenIds": [
                        13
                    ]
            }...
            {
                "name": "recipient.referenceNo",
                "value": null,
                "confidence": 0.909761641998803,
                "boundingBox": null
            }...
        ]
}

In the response json, extractions are returned under results > fields for each of the fields in the AI product selected in the request (see marketplace for details of each field).

Postman Collection

To help you get started we have put together a simple postman collection to demonstrate the process of uploading a file, running the sypht.extract workflow on the file and then checking for results.

5KB

Sypht Demo.postman_collection.json

Once you have imported the collection, you simply need to set up an environment with your API credentials (client id and client secret). You can find your credentials in the sypht app.