Documentation

MLS board setup

Connect a real board over the RESO Web API — vendor credentials, the two services that need board identity, and the compliance policy you must register.

The kit syncs real MLS listings through a RESO Web API connector — the NAR-mandated data standard implemented by MLS Grid, Trestle (CoreLogic/Cotality), Bridge Interactive, Spark API, and most modern MLS data vendors. It is not tied to any one of them.

Configuring your board touches three places: two separate backend services' environment variables, and one committed TypeScript file.

1. Get vendor credentials

Contact your MLS, or the vendor they use for RESO Web API access, and get credentials, a base URL, and confirmation of which board or dataset you are licensed for.

This table is a reference. Verify against your own vendor contract — it is not a substitute for it.

Vendor Auth Typical board-scope filter Notes
MLS Grid Static bearer token (no expiry) OriginatingSystemName Requires Accept-Encoding: gzip; forbids hotlinking media, so you must download and re-host
Trestle (CoreLogic/Cotality) OAuth2 client-credentials Often none — the credential implies scope Tokens expire ~8h, refreshed automatically
Bridge Interactive Client ID/secret ("server token") Varies by dataset
Spark API (FBS) OAuth2 client-credentials Varies Exposes RESO Web API at /Reso/OData

2. Run the diagnostic

Decide whether your auth is static (one long-lived token) or oauth2_client_credentials. Then run the read-only diagnostic:

npm run sample-pull --workspace=@frontstead/mls-service

It reports a guessed ID prefix (MLS Grid's ACTRIS boards use ACT, for example), field completeness, and the distinct listing-status values your board actually uses. Run this before writing config — boards vary more than their documentation suggests.

3. Configure the worker

Copy apps/mls-service/.env.example to .env and fill in:

  • MLS_AUTH_TYPE, MLS_BASE_URL, and the credentials for your auth type — MLS_ACCESS_TOKEN for static; MLS_OAUTH_TOKEN_URL / MLS_OAUTH_CLIENT_ID / MLS_OAUTH_CLIENT_SECRET for OAuth2
  • MLS_BOARD_ID — required, no default
  • MLS_BOARD_SCOPE_FIELD and MLS_BOARD_SCOPE_VALUE — only if your vendor needs an explicit filter to narrow to your board
  • MLS_PREFIX — if sample-pull found one

4. Configure the API with the same board identity

apps/api runs agent MLS-membership verification independently of the worker. They are separate deployable services with separate environments, so set the identical values again:

apps/api/.env
MLS_BOARD_ID=<same value as mls-service>MLS_PREFIX=<same value as mls-service, if any>MLS_PROVIDER_ID=<same value as mls-service, if you set one>

This is a genuine two-places-to-configure reality, not a naming inconsistency — the services do not share an environment, so there is no way around setting it twice.

Get it wrong and agent onboarding (POST /api/agent/mls/verify) either returns a 500 when MLS_BOARD_ID is missing, or silently fails to match a real agent when the two values differ. The silent failure is the one that costs you an afternoon.

5. Register your board's compliance policy

IDX/VOW display rules — attribution requirements, disclaimer text — are set by your MLS's data license agreement and genuinely differ board to board. The kit does not guess at them.

Add an entry to MLS_BOARD_POLICIES in packages/portal-config/src/mlsBoardPolicy.ts, using the existing Canopy MLS entry as a template. This is a committed TypeScript file you fork and edit, not an environment variable — the same idiom as portal.config.ts.

An unregistered board fails loud: at config-load time, and again anywhere getMlsBoardPolicy() is called for compliance gating. It does not silently default to "no attribution required," because a wrong guess there is a real compliance violation rather than a display bug.

6. Set your portal's board scope

In packages/portal-config/src/portal.config.ts, set listings.boardIds to your board's MLS_BOARD_ID.

7. Deploy and read the logs

Start apps/mls-service and check what it tells you:

Log state Meaning
No MLS_AUTH_TYPE set Idle warning, sync disabled — expected before you configure a vendor
Credentials set, MLS_BOARD_ID missing Hard startup error, non-zero exit. Fix the environment and redeploy
Otherwise Normal sync metrics logged per run

8. Verify agent onboarding

Submit a real MLS ID through POST /api/agent/mls/verify and confirm it resolves to verified against your board's synced roster.

9. Before you enable public display

MLS display is off by default:

MLS_PUBLIC_DISPLAY_ENABLED=false

Set the same value on both the API and the worker. Work through Display compliance before flipping it on, run the authenticated property reindex, and complete the end-to-end checks there before restoring public traffic.

Keep board-specific agreements, legal review, and approval evidence outside the public repository.

Next

Display compliance — the checklist before anything goes public.