GET /api/comparison

Builds a per-Unit source-vs-canonical comparison by downloading both the original uploaded File and the extracted output, then walking the column mapping to match source cells to canonical fields. Used to power the side-by-side review UI.

Request

Method: GET

Query Parameters:

Headers: Authorization: Bearer <token>

GET /api/comparison?job_id=abc-123-def
Authorization: Bearer <token>

Prerequisites

• The job must have status = complete
• The job must have a structure_result
• Both the original File and the Output File (outputs/{job_id}/output.xlsx) must exist in storage

Processing Steps

1. Authenticate via checkAuth()
2. Validate query parameter and fetch the job row
3. Download original File from Supabase Storage using storage_path
4. Parse original into CellGrid objects via readExcelBuffer()
5. Download Output File from outputs/{job_id}/output.xlsx
6. Parse output and extract rows from the Rent Roll Sheet
7. Build comparison — for each extracted Unit (up to 200):
   • Locate the source row in the original grid by matching unit_id
   • Collect all non-empty source cells for that row
   • Map each column in column_mapping to its canonical field
   • Classify each field as mapped, transformed, or missing

Unit Cap

The comparison is limited to the first 200 Units. For Files with more than 200 Units, only the first 200 are included in the response. This keeps payload sizes manageable for the review UI.

Diff Classification

Each field where the source and canonical values diverge is classified into one of three types:

Response

Success (200):

{
  "units": [
    {
      "unitId": "101",
      "sourceRowNumber": 5,
      "sourceCells": [
        { "column": "A", "header": "Unit #", "value": "101" },
        { "column": "B", "header": "Resident", "value": "John Smith" },
        { "column": "C", "header": "Sq Ft", "value": "850" },
        { "column": "D", "header": "Rent", "value": "$1,200.00" }
      ],
      "canonicalFields": {
        "unit_id": "101",
        "tenant_name": "John Smith",
        "sqft": 850,
        "market_rent": 1200
      },
      "differences": [
        {
          "canonicalField": "market_rent",
          "sourceColumn": "D",
          "sourceValue": "$1,200.00",
          "canonicalValue": 1200,
          "type": "transformed"
        }
      ]
    }
  ]
}

Response Types

ComparisonUnit

ComparisonDiff

Validation Errors