Developer Documentation

Getting Started

The SourceMLS API allows you to request verified badges for real estate listings and retrieve attribution information. All requests are authenticated using JWT tokens that link listings to their MLS organizations and authorized licensees.

Quick Start

1. Register for a SourceMLS account
2. Configure your MLS organization settings
3. Obtain your organization's secret key
4. Generate a JWT token with listing and licensee information
5. Make API requests using your JWT token
6. Display badges and attribution on your website

Data Model Overview

Authentication

All API requests require a valid JWT token. Tokens should be generated using your organization's secret key and must include required claims using RESO Data Dictionary standard field names.

Required JWT Claims (RESO Format)

{
  "SourceSystemID": "your-org-code",
  "LicenseeID": "licensee-key-from-mls",
  "LicenseeName": "ABC Realty Group",
  "ListingID": "MLS-2026-12345",
  "StandardStatus": "Active",
  "ModificationTimestamp": "2026-02-01T17:30:00Z"
}

Claim Descriptions

API Endpoints

<img src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.png" alt="SourceMLS Verified">

<iframe src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.html" width="300" height="200"></iframe>

<script src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.js"></script>

{
  "data": {
    "badge_html": "<div class=\"sourcemls-badge\">...</div>",
    "attribution": "John Doe Real Estate",
    "listing_address": "123 Main St, Springfield, IL 62701",
    "mls_organization": "Demo MLS Board"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2025-11-19T17:30:00Z",
    "warnings": []
  }
}

{
  "success": true,
  "badge_html": "<div class=\"sourcemls-badge\">...</div>",
  "request_id": "request-uuid"
}

{
  "listing": {
    "mls_number": "ML123456",
    "address": "123 Main St, Springfield, IL 62701",
    "price": "$250,000",
    "bedrooms": 3,
    "bathrooms": 2.5,
    "square_feet": 1800
  },
  "organization": {
    "name": "Demo MLS Board",
    "code": "DEMO_MLS",
    "attribution_template": "Listing courtesy of {{licensee_name}}",
    "disclaimer_text": "Information deemed reliable but not guaranteed"
  },
  "licensee": {
    "name": "Premium Realty Group"
  },
  "disclaimer": "Information deemed reliable but not guaranteed",
  "attribution_html": "<div class=\"sourcemls-attribution\">...</div>",
  "timestamp": "2025-11-12T10:30:00Z"
}

Badge Display

Display SourceMLS badges on your website using multiple integration methods. Choose the format that best fits your implementation.

Method 1: PNG Image (Simplest)

Embed the badge as a simple image - works everywhere, no JavaScript required.

<!-- Direct image embed -->
<img src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.png" 
     alt="SourceMLS Verified" 
     width="200">

Method 2: JavaScript Embed (Dynamic)

Embed via script tag - automatically inserts badge HTML and exposes listing data.

<!-- JavaScript embed - simplest dynamic option -->
<script src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.js"></script>

<!-- Access listing data after script loads -->
<script>
  // Data is available at window.SourceMLSBadge.data
  console.log(window.SourceMLSBadge.data);
</script>

Method 3: HTML Iframe

Embed complete styled badge HTML in an iframe.

<!-- Iframe embed -->
<iframe src="https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.html" 
        width="300" 
        height="200" 
        frameborder="0"></iframe>

Method 4: JSON API (Custom)

Fetch JSON data and build your own custom badge UI.

<!-- Fetch badge data and display -->
<div id="sourcemls-badge"></div>
<script>
fetch('https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.json')
  .then(response => response.json())
  .then(data => {
    // Use the pre-rendered HTML
    document.getElementById('sourcemls-badge').innerHTML = data.data.badge_html;
    
    // Or build custom UI with the data
    console.log('Listing:', data.data.listing_address);
    console.log('Organization:', data.data.mls_organization);
    console.log('Attribution:', data.data.attribution);
    
    // Check for warnings
    if (data.meta.warnings.length > 0) {
      console.warn('Badge warnings:', data.meta.warnings);
    }
  });
</script>

Method 5: Fetch HTML Directly

Fetch the HTML format and insert it directly.

// Fetch badge HTML and display
fetch('https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/badge.html')
  .then(response => response.text())
  .then(html => {
    document.getElementById('badge').innerHTML = html;
  })
  .catch(error => {
    console.error('Error loading badge:', error);
  });

Attribution Display

Display attribution information when users interact with badges.

Fetch Attribution (HTML)

fetch('https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/attribution')
  .then(response => response.text())
  .then(html => {
    document.getElementById('attribution').innerHTML = html;
  });

Fetch Attribution (JSON)

fetch('https://www.sourcemls.org/api/v1/YOUR_JWT_TOKEN/attribution_json')
  .then(response => response.json())
  .then(data => {
    // Access structured attribution data
    console.log('MLS Organization:', data.organization.name);
    console.log('Licensee:', data.licensee.name);
    console.log('Listing:', data.listing.address);
    console.log('Disclaimer:', data.disclaimer);
    
    // Or use the pre-formatted HTML
    document.getElementById('attribution').innerHTML = data.attribution_html;
  });

Code Examples

Ruby (Rails)

require 'jwt'

# Generate JWT token with RESO field names
payload = {
  SourceSystemID: 'your-org-code',          # Your MLS organization code
  LicenseeID: 'LIC-12345',                   # Licensee key from your MLS system
  LicenseeName: 'ABC Realty Group',          # Licensee display name
  ListingID: 'MLS-2026-12345',               # Listing identifier (MLS number)
  StandardStatus: 'Active',                  # Current listing status
  ModificationTimestamp: Time.current.iso8601
}

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

# Use in badge URLs - multiple format options
badge_png_url = "https://www.sourcemls.org/api/v1/#{token}/badge.png"
badge_html_url = "https://www.sourcemls.org/api/v1/#{token}/badge.html"
badge_js_url = "https://www.sourcemls.org/api/v1/#{token}/badge.js"
badge_json_url = "https://www.sourcemls.org/api/v1/#{token}/badge.json"

# Make API request (JSON format)
require 'net/http'
uri = URI(badge_json_url)
response = Net::HTTP.get_response(uri)
badge_data = JSON.parse(response.body)

# Access badge data
puts badge_data['data']['listing_address']
puts badge_data['data']['attribution']

JavaScript (Node.js)

const jwt = require('jsonwebtoken');

// Generate JWT token with RESO field names
const payload = {
  SourceSystemID: 'your-org-code',          // Your MLS organization code
  LicenseeID: 'LIC-12345',                   // Licensee key from your MLS system
  LicenseeName: 'ABC Realty Group',          // Licensee display name
  ListingID: 'MLS-2026-12345',               // Listing identifier (MLS number)
  StandardStatus: 'Active',                  // Current listing status
  ModificationTimestamp: new Date().toISOString()
};

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

// Use in badge URLs - multiple format options
const badgeUrls = {
  png: `https://www.sourcemls.org/api/v1/${token}/badge.png`,
  html: `https://www.sourcemls.org/api/v1/${token}/badge.html`,
  js: `https://www.sourcemls.org/api/v1/${token}/badge.js`,
  json: `https://www.sourcemls.org/api/v1/${token}/badge.json`
};

// Make API request (JSON format)
fetch(badgeUrls.json)
  .then(res => res.json())
  .then(data => {
    console.log('Listing:', data.data.listing_address);
    console.log('Attribution:', data.data.attribution);
  });

PHP

<?php
require_once 'vendor/autoload.php';
use \Firebase\JWT\JWT;

// Generate JWT token with RESO field names
$payload = array(
    "SourceSystemID" => "your-org-code",          // Your MLS organization code
    "LicenseeID" => "LIC-12345",                   // Licensee key from your MLS system
    "LicenseeName" => "ABC Realty Group",          // Licensee display name
    "ListingID" => "MLS-2026-12345",               // Listing identifier (MLS number)
    "StandardStatus" => "Active",                  // Current listing status
    "ModificationTimestamp" => date('c')
);

$token = JWT::encode($payload, $_ENV['MLS_SECRET_KEY'], 'HS256');

// Use in badge URLs - multiple format options
$badgePngUrl = "https://www.sourcemls.org/api/v1/{$token}/badge.png";
$badgeHtmlUrl = "https://www.sourcemls.org/api/v1/{$token}/badge.html";
$badgeJsUrl = "https://www.sourcemls.org/api/v1/{$token}/badge.js";
$badgeJsonUrl = "https://www.sourcemls.org/api/v1/{$token}/badge.json";

// Make API request (JSON format)
$response = file_get_contents($badgeJsonUrl);
$badgeData = json_decode($response, true);

// Access badge data
echo $badgeData['data']['listing_address'];
echo $badgeData['data']['attribution'];
?>

Best Practices

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"
  }
}

Rate Limiting

API requests are rate limited per organization to ensure fair usage and system stability.

Contact your account administrator to adjust rate limits for your organization.