Kaaj Invoice Analysis API

This document describes the API endpoint for processing and analyzing invoices. The endpoint accepts a list of invoice PDF files (each with an associated appId) and returns enriched invoice data along with various analysis reports.

---

Endpoint

POST https://api.kaaj.ai/application/invoice-analysis

---

Headers

Authorization: Bearer <your_api_key> Content-Type: multipart/form-data

Request Body

The request is submitted as multipart/form-data and must include:

• PDF Files: One or more invoice PDF files.
• JSON Metadata: A JSON field named metadata containing an array of objects. Each object must include:
  • appId (string, required): Unique identifier for the application/form associated with the PDF file.
  • fileName (string, required): Name of the corresponding PDF file.

Example Metadata (as a JSON field)

{
  "appId": "APP987654",
  "fileName": "invoice_1.pdf",
  "fileContent": "base64 encoded file content"
}

Extracted Invoice Data

Our AI models extract and structure invoice data, categorizing them into meaningful fields.

Basic Invoice Information

Field Name	Description
total_invoice_value	The total value of the invoice.
doc_type	The type of document.
file_id	The unique invoice number assigned by the sender.

Sender Information

Field Name	Description
sender_name	The name of the invoice issuer (seller).
sender_address	The address of the sender.
is_address_valid	validation status of the sender address.
validated_address_data	Validated address data.

Receiver Information

Field Name	Description
name	The name of the invoice recipient (buyer).
address	The address of the receiver.
is_address_valid	validation status of the sender address.
validated_address_data	Validated address data.

Invoice Line Items

Each invoice contains multiple transactions, categorized into detailed components.

Field Name	Description
date	The date of the transaction.
description	A description of the product/service billed.
category	Classification of the item (e.g., "hard" for tangible goods, "soft" for services).
rate (in $)	The per-unit price of the item/service.
amount (in $)	The total amount for the transaction.

Analysis Reports

The API performs multiple analyses on invoices, generating reports for deeper financial insights.

Generated Reports

• Invoice Summary: Aggregated view of invoice details.
• Transaction Breakdown: Categorization of invoice transactions.
• Vendor Analysis: Insights into vendors and supplier transactions.
• Payment Terms: Analysis of payment deadlines and due amounts.
• Tax & Fees: Breakdown of tax components and additional fees.

Response

The API returns JSON containing multiple analysis reports:

• Extracted Invoice Data: Structured data from the invoice.
• Analytical Reports: Additional sheets for detailed analysis:
  • Invoice Summary
  • Transaction Breakdown
  • Vendor Analysis
  • Payment Terms
  • Tax & Fees

Success Response

• Code: 200 OK
• Content: JSON object with the following fields:

{
  "id": 151,
  "sender": {
    "name": "The Peterbilt Store - Greenville",
    "address": "PO Box 6358, Knoxville, TN 37914",
    "is_address_valid": false,
    "validated_address_data": null
  },
  "receiver": {
    "name": "ET Transportation LLC",
    "address": "5364 Poplar Blvd., North Highlands, CA 95660-4936",
    "is_address_valid": true,
    "validated_address_data": {
      "city": "North Highlands",
      "label": "5364 Poplar Blvd, North Highlands, CA 95660-4936, United States",
      "state": "California",
      "county": "Sacramento",
      "street": "Poplar Blvd",
      "district": "North Highlands",
      "stateCode": "CA",
      "postalCode": "95660-4936",
      "countryCode": "USA",
      "countryName": "United States",
      "houseNumber": "5364"
    }
  },
  "total_invoice_value": 148225.0,
  "transactions": [
    {
      "date": "08/07/2024",
      "rate": 147200.0,
      "amount": 147200.0,
      "category": "hard",
      "description/item": "Sold Unit(s)"
    },
    {
      "date": "08/07/2024",
      "rate": 750.0,
      "amount": 750.0,
      "category": "hard",
      "description/item": "Total 360 90 Day Warranty"
    },
    {
      "date": "08/07/2024",
      "rate": 275.0,
      "amount": 275.0,
      "category": "soft",
      "description/item": "Processing Fee"
    }
  ],
  "file_id": 8494,
  "doc_type": "invoice",
  "created_at": "2025-02-14T16:48:04.134149+00:00",
  "other_details": {
    "vin": "1XPXD49X5MD750226",
    "make": "PETERBILT",
    "year": "2021",
    "model": "389",
    "titled": true,
    "down_payment": 29645.0,
    "equipment_age": 3,
    "equipment_type": "Truck",
    "equipment_miles_hours": null
  }
}

Error Responses

400 Bad Request

Occurs if required fields are missing.

{
  "message": "Missing required fields: ensure all PDF files and corresponding metadata (appId and fileName) are provided."
}

415 Unsupported Media Type

Occurs if an unsupported file format is provided.

{
  "message": "Unsupported file type. Only PDF files are allowed."
}

Additional Notes

• File Upload Limitations: Each PDF file must adhere to the 25MB size limit.
• Processing Time: Processing may take several minutes depending on the number and size of the invoices.
• Logging: All requests are logged, including file metadata, for auditing and troubleshooting.
• Download URL Validity: The provided download URL for the Excel file is valid for 24 hours.