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.

Recommended: No-JavaScript Badge

Place this tag on each listing detail page, using the SourceMLSURL from that listing's feed data. Replace {current-page-url} with the URL of the page displaying the badge:

<img src="{SourceMLSURL}.png?loc={current-page-url}"
     width="132"
     height="60"
     alt="Source MLS Verified" />

How Each Attribute Works

Sample Badge Image

There is a sample badge image at https://sourcemls.org/sample-badge.png that you can use for testing image sizing and placement before your MLS starts providing real SourceMLSURLs in the feed.

Legacy: JavaScript Badge (Deprecated)

This older implementation uses JavaScript to confirm badge impressions and hide invalid badges. It remains fully functional for existing integrations:

<img src="{SourceMLSURL}.png"
     width="132"
     height="60"
     alt="Source MLS Verified"
     onload="navigator.sendBeacon('{SourceMLSURL}',window.location.href)"
     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.

Exporting Data

Vendors can programmatically export usage data from Source MLS using the Export API. This enables automated reporting workflows using the same MLS secret key used to generate SourceMLSURLs.

How It Works

POST /api/v1/export

Create a new export request. Returns 202 Accepted with an export ID for polling.

Parameters

Valid Export Types

Valid Time Frames

Preset windows are exact to the second. GET /api/v1/export/:id reports the precise start_date and end_date the export covered, whichever time frame you used.

Custom Time Frames

Set time_frame to "custom" and supply both start_date and end_date in ISO 8601 format to export an exact period — a billing month, an audit window, or a backfill.

Request Example

curl -X POST https://sourcemls.org/api/v1/export \
  -H "Content-Type: application/json" \
  -d '{
    "mls_secret_key": "your_secret_key_here",
    "export_type": "badge_requests_detail",
    "time_frame": "last_30_days",
    "file_format": "json"
  }'

Request Example — Custom Time Frame

Export every badge request in July 2026. The lower bound is inclusive and the upper bound is exclusive, so this covers 2026-07-01T00:00:00Z up to but not including 2026-08-01T00:00:00Z.

curl -X POST https://sourcemls.org/api/v1/export \
  -H "Content-Type: application/json" \
  -d '{
    "mls_secret_key": "your_secret_key_here",
    "export_type": "badge_requests_detail",
    "time_frame": "custom",
    "start_date": "2026-07-01T00:00:00Z",
    "end_date": "2026-08-01T00:00:00Z",
    "file_format": "csv"
  }'

Poll GET /api/v1/export/:id to confirm the exact window the export covered — the response echoes the resolved time_frame, start_date, and end_date at every status, including queued and failed.

{
  "export_id": "8f14e45f-ceea-467a-9575-1f1e0dcb2f13",
  "status": "completed",
  "export_type": "badge_requests_detail",
  "file_format": "csv",
  "time_frame": "custom",
  "start_date": "2026-07-01T00:00:00Z",
  "end_date": "2026-08-01T00:00:00Z",
  "download_url": "https://s3.amazonaws.com/...",
  "expires_at": "2026-08-31T12:00:00Z",
  "row_count": 48213,
  "file_size_bytes": 6104922
}

Response (202 Accepted)

{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "export_type": "badge_requests_detail",
  "file_format": "json",
  "message": "Export queued. Poll GET /api/v1/export/:id for status, or await webhook delivery."
}

GET /api/v1/export/:id

Check the status of an export request. Pass your mls_secret_key as a query parameter. The response fields vary based on the export status.

Request Example

curl "https://sourcemls.org/api/v1/export/EXPORT_ID?mls_secret_key=your_secret_key_here"

Response — Queued or In Progress

{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "export_type": "badge_requests_detail",
  "file_format": "json"
}

Response — Completed

{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "export_type": "badge_requests_detail",
  "file_format": "json",
  "download_url": "https://s3.amazonaws.com/...",
  "expires_at": "2026-03-14T12:00:00Z",
  "row_count": 1523,
  "file_size_bytes": 245678
}

When the status is "completed", use the download_url to download the file. The download link expires at the time shown in expires_at (72 hours after generation).

Response — Failed

{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "export_type": "badge_requests_detail",
  "file_format": "json",
  "error_message": "An error occurred during export generation"
}

Polling Example

A simple polling loop to wait for an export to complete:

#!/bin/bash
# Request an export
RESPONSE=$(curl -s -X POST https://sourcemls.org/api/v1/export \
  -H "Content-Type: application/json" \
  -d '{
    "mls_secret_key": "your_secret_key_here",
    "export_type": "badge_requests_detail",
    "time_frame": "last_30_days"
  }')

EXPORT_ID=$(echo $RESPONSE | jq -r '.export_id')
echo "Export ID: $EXPORT_ID"

# Poll until complete
while true; do
  STATUS_RESPONSE=$(curl -s "https://sourcemls.org/api/v1/export/$EXPORT_ID?mls_secret_key=your_secret_key_here")
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    DOWNLOAD_URL=$(echo $STATUS_RESPONSE | jq -r '.download_url')
    echo "Download URL: $DOWNLOAD_URL"
    curl -o export.csv "$DOWNLOAD_URL"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Export failed: $(echo $STATUS_RESPONSE | jq -r '.error_message')"
    break
  fi

  echo "Status: $STATUS - waiting..."
  sleep 5
done

Webhook Alternative

Instead of polling, you can provide a webhook_url in your export request. When the export completes, Source MLS will send a POST request to your webhook URL with the export details including the download_url.

curl -X POST https://sourcemls.org/api/v1/export \
  -H "Content-Type: application/json" \
  -d '{
    "mls_secret_key": "your_secret_key_here",
    "export_type": "analytics_overview",
    "time_frame": "current_month",
    "file_format": "csv",
    "webhook_url": "https://your-server.com/webhooks/export-ready"
  }'

Real-Time Stats

Get real-time badge request counts for your organization or individual listings. These lightweight endpoints return instantly and are designed for integration with vendor dashboards. They use the same MLS secret key as the Export API.

GET /api/v1/stats

Returns badge request counts for your entire MLS organization across four time windows.

Request Example

curl "https://sourcemls.org/api/v1/stats?mls_secret_key=your_secret_key_here"

Response (200 OK)

{
  "mls_code": "M00000389",
  "mls_name": "Doorify MLS",
  "counts": {
    "last_hour": 142,
    "last_24_hours": 3850,
    "last_7_days": 24300,
    "all_time": 185420
  }
}

GET /api/v1/stats/:listing_key

Returns badge request counts for a specific listing. The :listing_key is the listing's unique identifier (the same ListingID value used in your JWT tokens).

Request Example

curl "https://sourcemls.org/api/v1/stats/OC25012345?mls_secret_key=your_secret_key_here"

Response (200 OK)

{
  "mls_code": "M00000389",
  "mls_name": "Doorify MLS",
  "listing_key": "25012345",
  "counts": {
    "last_hour": 8,
    "last_24_hours": 45,
    "last_7_days": 312,
    "all_time": 2840
  }
}

Custom Time Frame

Instead of the fixed windows, request a count for an exact period by setting time_frame=custom with ISO 8601 start_date and end_date parameters. The bound rules are identical to the Export API — inclusive lower bound, exclusive upper bound, both required together, and values without a timezone offset interpreted as UTC.

A custom window replaces the counts object with a single count — it does not add to it. Omit these parameters entirely and the response is exactly the fixed-window response shown above. If you need both, make two requests.

Request Example — Custom Time Frame

curl "https://sourcemls.org/api/v1/stats/OC25012345?mls_secret_key=your_secret_key_here&time_frame=custom&start_date=2026-07-01T00:00:00Z&end_date=2026-08-01T00:00:00Z"

Response (200 OK)

{
  "mls_code": "M00000389",
  "mls_name": "Doorify MLS",
  "listing_key": "25012345",
  "time_frame": "custom",
  "start_date": "2026-07-01T00:00:00Z",
  "end_date": "2026-08-01T00:00:00Z",
  "count": 1284
}

Count Time Windows

Returned when no time_frame parameters are supplied. A custom window replaces this object entirely.

Error Handling

All API endpoints return standard HTTP status codes and a consistent JSON error format.

HTTP Status Codes

Error Response Format

All errors return a JSON body with a consistent structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": "Additional context (may be null)"
  }
}

Error Codes