Tenant Portal API Routes

The myProp Tenant Portal exposes a set of tRPC procedures (registered at tenant.*) that connect to the AgentOS (letmc.com) API. These routes cover two distinct tenant contexts: active tenants (currently renting) and prospect tenants (searching for a property).

All procedures require authentication. Mutations additionally validate their inputs using Zod schemas.

---

Active Tenant

Active tenant endpoints surface real-time data about current and past tenancies, maintenance, certificates, and finances.

Tenancies

tenant.getTenantTenancies

Returns a paginated list of the tenant's current and historical tenancies.

Input:

Field	Type	Description
shortName	string	Agency short name (AgentOS identifier)
tenantId	string	Tenant identifier
offset	number (optional)	Pagination offset
count	number (optional)	Page size

Returns: Array of TenancySummary objects.

---

tenant.getTenancyDetails

Returns a single tenancy with full bundled data.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
tenancyId	string	Tenancy identifier

Returns: A TenancySummary object including address, rent amount and frequency, co-tenant names, deposit scheme, landlord name, and managing agent.

---

Maintenance

tenant.getTenantMaintenanceJobs

Returns a paginated list of maintenance jobs for the tenant, with optional client-side status filtering.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
offset	number (optional)	Pagination offset
count	number (optional)	Page size

Returns: Array of TenantMaintenanceJob objects.

---

tenant.getTenantMaintenanceJobDetails

Returns full details for a single maintenance job.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
jobId	string	Maintenance job identifier

Returns: A TenantMaintenanceJob object.

---

tenant.getTenantMaintenanceJobNotes

Returns notes attached to a maintenance job. This is a non-critical endpoint — if the AgentOS API returns an error, an empty array is returned rather than propagating the failure.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
jobId	string	Maintenance job identifier

Returns: Array of TenantJobNote objects, or [] on failure.

---

Certificates

tenant.getTenantCertificates

Returns property certificates relevant to the tenant (gas safety, EPC, EICR). Non-critical — returns an empty array if the agency does not have this feature enabled or if the endpoint fails.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier

Returns: Array of TenantCertificate objects, or [] on failure.

---

Financial Statements

tenant.getTenantStatements

Returns rent and financial statement entries for the tenant, optionally filtered by date range.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
from	string (optional)	Start date (ISO 8601)
to	string (optional)	End date (ISO 8601)

Returns: A TenantStatement object with:

• entries — individual transaction lines
• openingBalance, closingBalance
• totalDebits, totalCredits
• periodStart, periodEnd

---

Dashboard Insights

tenant.getTenantInsights

Aggregates multiple data points in parallel to produce dashboard KPIs for the tenant. Uses Promise.allSettled so a partial failure in one data source does not block the others.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier

Returns: A TenantInsights object:

{
  currentTenancy: TenancySummary | null;
  outstandingBalance: number;
  activeMaintenanceJobs: number;
  completedMaintenanceJobs: number;
  totalMaintenanceJobs: number;
  certificatesDueSoon: number;
  nextRentDue: string | null;
}

---

Prospect Tenant

Prospect tenant endpoints support tenants who are searching for a property and have not yet started a tenancy.

Application Profile

tenant.getTenantApplicationProfile

Fetches existing tenant profile data for pre-filling application forms.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier

Returns: A TenantApplicationProfile object with name, email, phone, date of birth, NI number, employer name, employer address, and annual income.

---

Advertised Properties

tenant.getAdvertisedProperties

Searches available properties to let, with optional branch filtering.

Input:

Field	Type	Description
shortName	string	Agency short name
branchId	string (optional)	Filter by branch
offset	number (optional)	Pagination offset
count	number (optional)	Page size

Returns: Array of AdvertisedProperty objects.

---

tenant.getAdvertisedPropertyDetails

Returns full details for a single advertised property, including all photo URLs.

Input:

Field	Type	Description
shortName	string	Agency short name
propertyId	string	Property identifier

Returns: An AdvertisedProperty object.

---

Preferences

tenant.getTenantPreferences

Fetches the prospect's property search preferences. Non-critical — returns default/empty preferences if the endpoint fails.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier

Returns: A TenantPreferences object with bedroom range, rent range, preferred areas, property types, furnished preference, pets, dependants, and move-in date.

---

tenant.updateTenantPreferences (mutation)

Updates the prospect's property search preferences via PUT to the AgentOS API.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
preferences	Partial<TenantPreferences>	Fields to update

Returns: Updated TenantPreferences object.

---

Viewings

tenant.getTenantViewings

Returns a list of scheduled viewings for the prospect tenant.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier

Returns: Array of TenantViewing objects.

---

tenant.scheduleViewing (mutation)

Books a new property viewing via POST to the AgentOS API.

Input:

Field	Type	Description
shortName	string	Agency short name
tenantId	string	Tenant identifier
propertyId	string	Property to view
dateTime	string	Requested date/time (ISO 8601)
notes	string (optional)	Additional notes

Returns: The created TenantViewing object.

---

Error Handling

Condition	Behaviour
AgentOS API not configured	Returns PRECONDITION_FAILED tRPC error
404 from AgentOS (feature not enabled)	Returns null or [] — does not throw
Non-critical endpoint failure (certificates, notes, preferences)	Returns default/empty value and logs via captureError
Partial failure in insights aggregation	Unaffected KPIs still returned; failed sources default to null/0

---

Data Normalisation

All AgentOS responses are normalised on ingestion:

• PascalCase field names are mapped to camelCase
• Alternative field names from the AgentOS API (e.g. EmailAddress vs Email, TenancyStart vs StartDate) are handled with fallback chains
• Address fields are assembled from Address1–Address4 + Postcode into a formatted string
• Array fields returned as strings (e.g. PreferredAreas) are split and trimmed