Invoice Analysis Overview

Invoice Analysis provides a powerful tool for mitigating Authorised Push Payment (APP) fraud. It provides signals on content accuracy and forensic risks within invoices to help detect anomalies and flag suspicious activity before payments are made.

With seamless integration available through Tunic Pay’s Invoice Analysis API, the detection of fraud patterns and inconsistencies can be automated to reduce manual review effort and enhance payment security. Signals about both content of an invoice and the file itself are analysed and made available to callers of the API.

This guide explains how to interact with the API and the key concepts it models.

Key Concepts

Undertaking an Invoice Analysis with the API is a two stage process:

1. Create an Upload to describe the content you want analysed.
2. After uploading, ask for an Analysis to be performed.

Upload

An Upload represents a file that you want to analyse. Uploads to the API are asynchronous.

1. Create an Upload:
   • Call the /uploads endpoint with the file name and type.
   • Receive an upload_id and a signed upload_url.
2. Upload File:
   • Use the signed upload_url to upload your invoice file.

Once the file is uploaded, you can start an analysis with reference to the upload_id you completed.

Note that upload_urls expire after a set time, so you should upload files promptly after creating an Upload object.

Note

An attempt to upload a file to an expired URL will result in a 400 Bad Request from the Storage service.

To resolve this, create a new Upload object by calling /uploads again, and use the new upload_id from the response to start an analysis. There is no need to explicitly delete the original expired Upload object.

Analysis

An Analysis represents the risk assessment process performed on a completed upload.

Different analyses can be performed on the uploaded file. These are requested when an analysis is started as part of the request:

• Content Analysis: Analysis on information contained within the document (e.g. invoice data).
• Forensic Analysis: Potential risks or anomalies related to the provenance of the document itself.

1. Start Analysis:
   • Call the /analyses endpoint with the upload_id and list of analysis types you want to perform (content, forensic).
   • Receive an analysis_id.
2. Check Status:
   • The /analyses/{analysis_id}/status endpoint can be polled to monitor progress.
3. Retrieve Results:
   • Call /analyses/{analysis_id}/results to fetch completed results.

Analysis lifecycle

Once requested, an analysis is executed asynchronously by Tunic Pay’s backend:

The /analyses/{analysis_id}/status endpoint can be polled to monitor progress.

At the point where a terminal FAILED or COMPLETED status is reached, the /analyses/{analysis_id}/results endpoint can be called to retrieve the actual result. Note that this endpoint returns a status field (which is guaranteed to match the value returned by /status). It’s recommended that API consumers use the lighter-weight /status endpoint until the analysis is finished to avoid unnecessary data transfer of a potentially large result set.

Analysis results

The responses at the /analyses/{analysis_id}/results contain different data depending on whether the analysis was successful and what specific analysis types were requested. Full details of the response schema are available in the API reference (COMING SOON).

{
    "analysis_id": "string",
    "status": "string",
    "error": {
        "code": "string",
        "message": "string"
    },
    "file_metadata": {
        "file_name": "string",
        "file_type": "string",
        "sha256": "string"
    },
    "content": {
        "invoice": {
            "number": "string"
            // ...
        }
    },
    "forensic": {
        "risk_level": "string"
        // ...
    }
}

For more details about the response structure, please see:

• API reference (COMING SOON)
• List of risk indicators

Authentication

All API requests require an API key, sent via the X-API-Key header. Please contact your account manager to obtain an API key.