Developer Documentation

Overview

Source MLS verifies that listing data displayed on real estate websites originates from an authorized MLS. Data Licensees, such as IDX Vendors, display a small badge on each listing detail page indicating this fact. The verification works through a simple SourceMLSURL that flows from the MLS to data Licensees via the RESO data feed.

How It Works

SourceMLSURL Format

https://sourcemls.org/api/v1/{jwt_token}/badge

The {jwt_token} is a signed JWT containing RESO Data Dictionary claims that identify the listing, licensee, and MLS organization. MLSs generate this token server-side using their organization secret key.

For Licensees

As a data Licensee, you receive a simple and unique SourceMLSURL for each listing in the RESO data feed from your MLS. To display the Source MLS badge on your listing detail pages, add the following <img> tag.

Badge Implementation

Place this tag on each listing detail page, using the SourceMLSURL from that listing's feed data:

<img src="{SourceMLSURL}.png"
     width="132"
     height="60"
     alt="Source MLS Verified"
     onload="navigator.sendBeacon('{SourceMLSURL}')"
     onerror="this.style.display='none'">

How Each Attribute Works

For MLSs

As an MLS Organization, you generate a simple SourceMLSURL for each listing in your RESO data feed. The URL contains a JWT token signed with your organization's secret key. It is unique for each listing and licensee combination, allowing you to track the source and location of each badge impression.

You will want to work with your RESO Vendor or data feed provider to implement this. The Source MLS system will provide you with a secret key and your RESO Unique Organization Identifier once you sign up. Share those with your RESO Vendor or data feed provider and they can take it from there using the instructions below.

JWT Token Generation

Create a JWT token with the following RESO Data Dictionary claims, signed using your organization's secret key with the HS256 algorithm.

Required Claims

Assembling the SourceMLSURL

After generating the JWT token, construct the SourceMLSURL:

https://sourcemls.org/api/v1/{jwt_token}/badge

Include this URL as a field in the RESO feed data for each listing.

Sample Code

JavaScript (Node.js)

const jwt = require('jsonwebtoken');

// Generate JWT token with RESO claims
const payload = {
  SourceSystemID: 'your-org-code',
  LicenseeID: 'LIC-12345',
  LicenseeName: 'ABC Realty Group',
  ListingID: 'MLS-2026-12345',
  StandardStatus: 'Active',
  ModificationTimestamp: new Date().toISOString()
};

const token = jwt.sign(payload, process.env.MLS_SECRET_KEY, { algorithm: 'HS256' });

// Assemble the SourceMLSURL
const sourceMLSURL = `https://sourcemls.org/api/v1/${token}/badge`;

Ruby

require 'jwt'

# Generate JWT token with RESO claims
payload = {
  SourceSystemID: 'your-org-code',
  LicenseeID: 'LIC-12345',
  LicenseeName: 'ABC Realty Group',
  ListingID: 'MLS-2026-12345',
  StandardStatus: 'Active',
  ModificationTimestamp: Time.current.iso8601
}

token = JWT.encode(payload, ENV['MLS_SECRET_KEY'], 'HS256')

# Assemble the SourceMLSURL
source_mls_url = "https://sourcemls.org/api/v1/#{token}/badge"

Python

import jwt
import os
from datetime import datetime

# Generate JWT token with RESO claims
payload = {
    'SourceSystemID': 'your-org-code',
    'LicenseeID': 'LIC-12345',
    'LicenseeName': 'ABC Realty Group',
    'ListingID': 'MLS-2026-12345',
    'StandardStatus': 'Active',
    'ModificationTimestamp': datetime.utcnow().isoformat() + 'Z'
}

token = jwt.encode(payload, os.environ['MLS_SECRET_KEY'], algorithm='HS256')

# Assemble the SourceMLSURL
source_mls_url = f'https://sourcemls.org/api/v1/{token}/badge'

JWT Checker Tool

Use our online JWT checker to validate and decode your tokens during development.

Error Handling

The API returns standard HTTP status codes and JSON error responses.

Error Response Format

{
  "error": {
    "message": "Invalid JWT token",
    "code": "INVALID_TOKEN",
    "details": "Token signature verification failed"
  }
}