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-serviceIt 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_TOKENfor static;MLS_OAUTH_TOKEN_URL/MLS_OAUTH_CLIENT_ID/MLS_OAUTH_CLIENT_SECRETfor OAuth2MLS_BOARD_ID— required, no defaultMLS_BOARD_SCOPE_FIELDandMLS_BOARD_SCOPE_VALUE— only if your vendor needs an explicit filter to narrow to your boardMLS_PREFIX— ifsample-pullfound 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:
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=falseSet 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.