Account Discovery API

The Account Discovery API is the primary post-login call in myProp. After a user authenticates, it queries the AgentOS platform to determine which portal account types — landlord, tenant, buyer, vendor, or contractor — are linked to their email address. The result determines which dashboards and features are presented to the user.

Overview

AgentOS exposes separate endpoints for each account type. myProp queries all five in parallel so the full picture is available in a single round-trip. Partial failures (e.g. an agency that has not enabled sales accounts) do not block the results from other types.

Supported Account Types

Type	AgentOS Area	Endpoint
landlord	lettings	/v3/{shortName}/lettings/landlords
tenant	lettings	/v3/{shortName}/lettings/tenants
buyer	sales	/v3/{shortName}/sales/buyers
vendor	sales	/v3/{shortName}/sales/vendors
contractor	lettings	/v3/{shortName}/lettings/contractors

tRPC Procedures

All procedures are available under the accountDiscovery router and require an authenticated session (protectedProcedure).

accountDiscovery.discover

Discovers all account types for the authenticated user. This is the standard post-login call.

Input

{
  shortName: string  // AgentOS agency short name / URL slug
}

Response

{
  accounts: PortalAccount[];       // All discovered accounts across all types
  accountTypes: {
    landlord:   { found: boolean; count: number; activeCount: number };
    tenant:     { found: boolean; count: number; activeCount: number };
    buyer:      { found: boolean; count: number; activeCount: number };
    vendor:     { found: boolean; count: number; activeCount: number };
    contractor: { found: boolean; count: number; activeCount: number };
  };
  errors: Array<{ type: string; message: string; status?: number }>;
  email: string;
  discoveredAt: string;  // ISO 8601 timestamp
}

Example (React)

const { data } = trpc.accountDiscovery.discover.useQuery({
  shortName: "acme-lettings"
});

// All discovered accounts
console.log(data.accounts);

// Per-type summary — use to decide which dashboards to show
if (data.accountTypes.landlord.found) {
  // Show landlord dashboard
}

---

accountDiscovery.discoverByType

Performs a targeted lookup for a single account type. Use this when you only need to check one type rather than running a full discovery.

Input

{
  shortName: string;
  type: "landlord" | "tenant" | "buyer" | "vendor" | "contractor";
}

Response

{
  accounts: PortalAccount[];
  errors: Array<{ type: string; message: string; status?: number }>;
  email: string;
  discoveredAt: string;
}

Example

const { data } = trpc.accountDiscovery.discoverByType.useQuery({
  shortName: "acme-lettings",
  type: "tenant"
});

---

accountDiscovery.status

Lightweight health check. Returns whether the AgentOS API is configured. Makes no external API call.

Input: none

Response

{
  available: boolean  // true if LETMC_API_KEY is configured
}

Example

const { data } = trpc.accountDiscovery.status.useQuery();
if (!data.available) {
  // AgentOS API not yet configured
}

---

The PortalAccount Type

Each discovered account is normalised to a consistent shape regardless of which AgentOS endpoint it came from:

interface PortalAccount {
  type: "landlord" | "tenant" | "buyer" | "vendor" | "contractor";
  accountId: string;        // AgentOS OID or GlobalReference
  displayName: string;      // Resolved from DisplayName or Title+Forename+Surname
  email: string;            // Email address on the account
  isActive: boolean;        // Derived from IsActive or inverse of Archived
  branchId: string | null;  // AgentOS branch/office identifier, if available
  metadata: Record<string, unknown>;  // Raw API fields for extended use
}

Error Handling

Scenario	Behaviour
AgentOS returns 404 for an account type	Silently skipped — indicates the agency has not enabled that type
AgentOS returns another non-2xx status	Error captured for observability; included in errors array; other types still returned
Invalid or missing email	Returns empty accounts array immediately without querying AgentOS
Missing shortName	Returns an error entry without querying AgentOS
LETMC_API_KEY not configured	status.available is false; discoverAccounts throws LetmcNotConfiguredError

Configuration

Account discovery uses the existing AgentOS API credentials — no additional environment variables are required:

Variable	Purpose
LETMC_API_KEY	Authenticates requests to the AgentOS API
LETMC_API_BASE_URL	Base URL for the AgentOS v3 API

Call accountDiscovery.status to verify these are present before triggering discovery.