Contractor Portal API Routes

Version 0.1.24 introduces the backend API layer for the Contractor Portal in myProp. These Next.js API routes connect the contractor-facing UI to the AgentOS platform, enabling contractors to self-serve without contacting their agency directly.

Overview

The Contractor Portal API is organised into three functional areas:

Area	Description
Account & Contacts	Retrieve contractor profile and associated contacts
Maintenance Jobs	List jobs, view notes, toggle completion, add notes
Financial	View historical and pending statements, submit invoices

All routes are implemented as Next.js API routes and communicate with the AgentOS (letmc.com) API on the server side.

Account & Contacts

Fetch Contractor Account

GET /api/contractor/account

Returns the authenticated contractor's account details as stored in AgentOS.

Response fields include:

Contractor name and identifier
Agency association
Account status

Fetch Contractor Contacts

GET /api/contractor/contacts

Returns the list of contacts linked to the contractor account (e.g. agency staff, property managers).

Maintenance Jobs

List Jobs with Notes

GET /api/contractor/jobs

Returns all maintenance jobs currently assigned to the contractor. Each job includes:

Job ID, description, and property details
Current completion status
Associated notes

Toggle Job Completion

PATCH /api/contractor/jobs/[jobId]/complete

Toggles the completion status of the specified maintenance job. If the job is marked incomplete, calling this endpoint marks it complete, and vice versa.

Path parameters:

Parameter	Type	Description
`jobId`	`string`	The unique identifier of the maintenance job

Add a Note to a Job

POST /api/contractor/jobs/[jobId]/notes

Appends a new note to the specified maintenance job. Useful for logging progress updates, materials used, or communication with the agency.

Path parameters:

Parameter	Type	Description
`jobId`	`string`	The unique identifier of the maintenance job

Request body:

{
  "note": "string"
}

Financial Statements

Historical Statements

GET /api/contractor/statements/historical

Returns a list of previously processed financial statements for the contractor. Use this to review past payments and reconciled work orders.

Pending Statements

GET /api/contractor/statements/pending

Returns statements that have been raised but are not yet processed or paid. Contractors can use this to track outstanding amounts.

Invoice Submission

Submit an Invoice

POST /api/contractor/invoices

Submits a new invoice from the contractor to the agency. Invoices are linked to maintenance jobs and/or pending statements within AgentOS.

Request body:

{
  "jobId": "string",
  "amount": "number",
  "description": "string",
  "invoiceDate": "string (ISO 8601)"
}

Note: Exact required fields may vary based on the AgentOS API schema. Refer to your agency's configuration for mandatory invoice fields.

Authentication

All Contractor Portal API routes require an authenticated session. Requests without a valid session token will return a 401 Unauthorized response. Authentication is handled via the myProp session layer before the request reaches the AgentOS API.

Error Handling

All routes follow a consistent error response shape:

{
  "error": "string"
}

Common HTTP status codes returned:

Status	Meaning
`200`	Success
`201`	Resource created (e.g. note or invoice submitted)
`400`	Bad request — missing or invalid parameters
`401`	Unauthenticated — no valid session
`404`	Resource not found
`500`	Internal server error or upstream AgentOS failure