Skip to main content
All Docs
API ReferencemyProp (AgentOS People Portal)Updated April 4, 2026

Buyer & Vendor Portal API

Buyer & Vendor Portal API

Introduced in v0.1.25, the buyer and vendor portal APIs expose tRPC endpoints that connect portal users — property buyers and vendors (sellers) — to their agency's AgentOS data in real time.

All endpoints are protected (authentication required) and follow the same patterns as the landlord, tenant, and contractor routers already in the platform.

Buyer Router (buyer.*)

Source files:

  • Service layer: src/lib/letmc/buyer.ts
  • tRPC router: src/lib/routers/buyer.ts

Procedures

buyer.status

Returns portal availability. Useful as a health check from the client.

buyer.insights

Returns aggregated dashboard KPIs for the authenticated buyer.

Response shape:

{
  totalViewings: number;
  upcomingViewings: number;
  completedViewings: number;
  totalOffers: number;
  activeOffers: number;
  acceptedOffers: number;
  alertsEnabled: boolean;
}

buyer.account

Fetches the buyer's full profile from AgentOS.

Response shape:

{
  buyerId: string;
  displayName: string;
  title: string | null;
  forename: string | null;
  surname: string | null;
  email: string | null;
  phone: string | null;
  mobile: string | null;
  address: string | null;
  addressLine1: string | null;
  addressLine2: string | null;
  addressLine3: string | null;
  postcode: string | null;
  isActive: boolean;
  branchId: string | null;
  metadata: Record<string, unknown>;
}

buyer.purchaseSituation

Retrieves the buyer's purchase situation, including chain status, mortgage status, and solicitor details.

Response shape:

{
  buyerId: string;
  hasPropertyToSell: boolean | null;
  isFirstTimeBuyer: boolean | null;
  isCashBuyer: boolean | null;
  mortgageAgreedInPrinciple: boolean | null;
  solicitorName: string | null;
  solicitorPhone: string | null;
  solicitorEmail: string | null;
  solicitorAddress: string | null;
  maxBudget: number | null;
  minBedrooms: number | null;
  maxBedrooms: number | null;
  preferredAreas: string[];
  propertyTypes: string[];
  additionalNotes: string | null;
  metadata: Record<string, unknown>;
}

buyer.updatePurchaseSituation

Updates the buyer's purchase situation record in AgentOS. Accepts the same fields returned by buyer.purchaseSituation.

buyer.propertyAlerts

Retrieves the buyer's saved search preferences and alert configuration.

Response shape:

{
  buyerId: string;
  isEnabled: boolean;
  minPrice: number | null;
  maxPrice: number | null;
  minBedrooms: number | null;
  maxBedrooms: number | null;
  propertyTypes: string[];
  preferredAreas: string[];
  alertFrequency: string | null;
  metadata: Record<string, unknown>;
}

buyer.updatePropertyAlerts

Updates the buyer's property alert settings. Accepts the same fields returned by buyer.propertyAlerts.

buyer.viewings

Returns a paginated list of viewings scheduled for the buyer.

Input:

{ offset?: number; count?: number }

Response item shape:

{
  viewingId: string;
  propertyId: string;
  propertyAddress: string | null;
  dateTime: string | null;
  status: string;
  notes: string | null;
  feedbackSubmitted: boolean;
  agentName: string | null;
  metadata: Record<string, unknown>;
}

buyer.submitViewingFeedback

Submits post-viewing feedback to AgentOS (rating, comments, interest level).

Response shape:

{
  feedbackId: string | null;
  success: boolean;
  message: string | null;
  metadata: Record<string, unknown>;
}

buyer.offers

Returns a paginated list of offers the buyer has submitted.

Input:

{ offset?: number; count?: number }

Response item shape:

{
  offerId: string;
  propertyId: string;
  propertyAddress: string | null;
  amount: number;
  status: string;
  submittedDate: string | null;
  respondedDate: string | null;
  conditions: string | null;
  agentNotes: string | null;
  metadata: Record<string, unknown>;
}

buyer.submitOffer

Submits a new offer on a sales property through AgentOS.

Response shape:

{
  offerId: string | null;
  success: boolean;
  message: string | null;
  metadata: Record<string, unknown>;
}

buyer.advertisedProperties

Searches and returns paginated for-sale property listings from AgentOS.

Input:

{ offset?: number; count?: number }

Response item shape:

{
  propertyId: string;
  address: string;
  price: number | null;
  priceQualifier: string | null;
  bedrooms: number | null;
  bathrooms: number | null;
  receptionRooms: number | null;
  propertyType: string | null;
  status: string | null;
  description: string | null;
  mainImageUrl: string | null;
  branchId: string | null;
  metadata: Record<string, unknown>;
}

buyer.advertisedPropertyDetails

Fetches full details for a single advertised sales property by ID.

Vendor Router (vendor.*)

Source files:

  • Service layer: src/lib/letmc/vendor.ts
  • tRPC router: src/lib/routers/vendor.ts

Procedures

vendor.status

Returns portal availability. Useful as a health check from the client.

vendor.insights

Returns aggregated dashboard KPIs for the authenticated vendor.

Response shape:

{
  instructionCount: number;
  totalViewings: number;
  totalOffers: number;
  highestOffer: number | null;
  averageDaysOnMarket: number | null;
}

vendor.account

Fetches the vendor's full profile from AgentOS.

vendor.instructions

Lists the vendor's active sales instructions (mandates), including property and marketing information.

vendor.instructionDetails

Fetches full details for a single sales instruction by ID.

vendor.instructionOffers

Returns offers received on a specific vendor instruction (property listing).

vendor.instructionViewings

Returns viewings arranged for a specific vendor instruction (property listing).

Common Patterns

Authentication

All procedures use protectedProcedure. Every request must be authenticated — unauthenticated calls will be rejected by the tRPC middleware.

Pagination

List endpoints accept optional offset and count parameters:

{ offset?: number; count?: number }

Defaults are applied server-side when parameters are omitted.

Error Handling

  • 404 from AgentOS: Returns null (single-record fetches) or [] (list fetches) — never throws.
  • Other errors: Captured via captureError for observability; a structured error is returned to the client.

AgentOS Integration

Both routers use letmcClient — the shared HTTP client with automatic retry and timeout. All calls are made using the agency's shortName and the user's AgentOS identifier (buyerId / vendorId), resolved from the authenticated session.