Installment AI API

Extract structured installment schedules from SPA (Sale & Purchase Agreement) documents using an AI parser backed by OpenAI Assistants.

Base URL: /api/installment-ai

Authentication & Authorization

• Auth: Cookie-based session (JWT in token cookie set by the Auth API).
• Required roles: admin, sales, finance, or agent.
• Middleware: authorize(["admin", "sales", "finance", "agent"]).
• Unauthenticated/unauthorized requests return 401 or 403 as configured globally.

Limits

• Max file size: 10 MB (enforced by multer).
• Accepted input: Single uploaded file in field file. Common formats include PDF/Word/Images; the service streams the raw buffer to OpenAI file search.

---

POST /parse

Uploads a SPA file, asks the AI assistant to extract payment milestones (installments, fees, post-handover items), and returns a normalized JSON payload.

Route

POST /api/installment-ai/parse

Headers

• Cookie: token=<JWT> (from the Login endpoint)
• Content-Type: multipart/form-data

Form Data

Field	Type	Required	Notes
file	File (binary)	Yes	SPA document to be parsed. Max 10 MB.

Response: 200 OK

{
  "success": true,
  "data": {
    "installments": [
      {
        "amount": 120000.0,
        "dueDate": "15-Mar-25",
        "description": "10% on SPA signing",
        "percentage": 10,
        "isFee": false,
        "postHandover": false,
        "status": "pending"
      }
    ]
  }
}

Field schema

Each installments[] item contains:

Field	Type	Required	Description
amount	number	Yes	Monetary amount for the milestone.
dueDate	string	Yes (may be empty)	Date in DD-MMM-YY (e.g., 05-Jan-26). If the SPA doesn’t specify, may be empty string.
description	string	Yes	Human-readable label from the SPA clause.
percentage	number	Yes	Percentage of total price for this item. May be 0 if unknown.
isFee	boolean	Yes	true for reservation/registration/admin/other fees.
postHandover	boolean	Yes	true if payment is due after handover.
status	string	Yes	Always returned as "pending" by this parser.

⚠️ Note: The AI attempts to extract all payments mentioned in the SPA, including Registration fees, NOC, and Administration fees, and marks such rows with isFee: true.

Error responses

Status	When	Body
400 Bad Request	No file or invalid form field	{ "success": false, "message": "No valid file uploaded." }
401/403	Not authenticated/authorized	Standard auth error shape.
413 Payload Too Large	File > 10 MB	Multer will reject large files.
500 Internal Server Error	OpenAI or parsing error	{ "success": false, "message": "<error message>" }

cURL example

curl -X POST \
  -b "token=YOUR_JWT" \
  -F "file=@/path/to/spa.pdf" \
  https://your.api.host/api/installment-ai/parse

JavaScript (fetch) example

const form = new FormData();
form.append("file", new File([blob], "contract.pdf"));

const res = await fetch("/api/installment-ai/parse", {
  method: "POST",
  body: form,
  credentials: "include", // send cookie token
});

if (!res.ok) throw new Error("Upload failed");
const data = await res.json();
console.log(data.data.installments);

---

Behavior & Implementation Notes

• The service uploads your file to OpenAI Assistants and a temporary Vector Store; then runs a custom Assistant (model: gpt-4o) with a strict JSON schema to ensure valid output. Internally the service:
  1. Creates a vector store and indexes the uploaded document.
  2. Creates an assistant configured for SPA extraction with file_search tool.
  3. Runs a thread asking for the full list of installments.
  4. Polls until completion and parses the assistant’s last message as JSON.
• The service returns only { success, data: { installments } } and does not persist results.
• Dates are returned in DD-MMM-YY format if found in the SPA; otherwise "".

Security & Privacy

• Documents are transmitted to OpenAI per your environment’s OPENAI_API_KEY and subject to OpenAI’s data handling. Review your organization’s compliance requirements before enabling.
• Uploaded files are limited to 10 MB and are used only for extraction in the current request flow.

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	API key used to call OpenAI Assistants and Vector Stores.

Troubleshooting

• Empty or partial results: Ensure the SPA is legible (text-based PDF preferable). Scanned images may reduce accuracy.
• Date format: If due dates are not present or ambiguous, dueDate may be an empty string.
• Fees detection: The model flags common fees (registration, NOC, admin). Verify and adjust downstream if needed.
• Large files: Reduce the file size to ≤ 10 MB.