{
  "openapi": "3.0.1",
  "info": {
    "title": "Zynplex API",
    "description": "Clean REST API on top of the CREA DDF® Web API. Public endpoints authenticate with an `X-API-KEY` header. Portal endpoints (`/portal/*`) authenticate with a Cognito JWT. Every response carries an `attribution` block — sites consuming this API must display REALTOR.ca branding.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "/dev"
    }
  ],
  "paths": {
    "/listings": {
      "get": {
        "tags": [
          "Listings"
        ],
        "summary": "Search listings",
        "description": "Returns a paged list of listings filtered by the supplied criteria. Supports price/beds/baths/size ranges, geographic radius search, polygon (WKT) bounding, and sort options.",
        "operationId": "ListingsSearch",
        "parameters": [
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "minBedrooms",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "maxBedrooms",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "minBaths",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "maxBaths",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "minSqft",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "maxSqft",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stateOrProvince",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "propertyType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transactionType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commonInterest",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listAgentKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listOfficeKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "long",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "map",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageNum",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "resultsPerPage",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListingSummarySearchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/listings/{mlsNumber}": {
      "get": {
        "tags": [
          "Listings"
        ],
        "summary": "Get a single listing",
        "description": "Lookup by MLS number or canonical ListingKey. Returns the full listing payload plus an attribution block.",
        "operationId": "ListingDetail",
        "parameters": [
          {
            "name": "mlsNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/listings/{mlsNumber}/history": {
      "get": {
        "tags": [
          "Listings"
        ],
        "summary": "Get price/status history for a listing",
        "operationId": "ListingHistory",
        "parameters": [
          {
            "name": "mlsNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/listings/{mlsNumber}/media": {
      "get": {
        "tags": [
          "Listings"
        ],
        "summary": "List photos and floorplans for a listing",
        "operationId": "ListingMedia",
        "parameters": [
          {
            "name": "mlsNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/listings/aggregates": {
      "get": {
        "tags": [
          "Listings"
        ],
        "summary": "Facet counts grouped by status, city, and bedrooms — used to power filter UIs.",
        "operationId": "ListingAggregates",
        "parameters": [
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "minBedrooms",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "maxBedrooms",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "minBaths",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "maxBaths",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "minSqft",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "maxSqft",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stateOrProvince",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "propertyType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transactionType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commonInterest",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listAgentKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listOfficeKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "long",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "map",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageNum",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "resultsPerPage",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/locations/autocomplete": {
      "get": {
        "tags": [
          "Locations"
        ],
        "summary": "City name autocomplete",
        "description": "Returns up to 20 city suggestions matching the prefix (case-insensitive). Backed by Postgres trigram index.",
        "operationId": "LocationsAutocomplete",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/members": {
      "get": {
        "tags": [
          "Members"
        ],
        "summary": "List agents",
        "description": "Filter by `agentName` (partial match), `agentId` (MLS ID), or `brokerage` (office key).",
        "operationId": "MembersList",
        "parameters": [
          {
            "name": "agentName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agentId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brokerage",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageNum",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "resultsPerPage",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/members/{memberKey}": {
      "get": {
        "tags": [
          "Members"
        ],
        "summary": "Get a single agent by MemberKey",
        "operationId": "MembersGet",
        "parameters": [
          {
            "name": "memberKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/offices": {
      "get": {
        "tags": [
          "Offices"
        ],
        "summary": "List brokerages",
        "description": "Filter by `name` (partial, case-insensitive match).",
        "operationId": "OfficesList",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pageNum",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "resultsPerPage",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/offices/{officeKey}": {
      "get": {
        "tags": [
          "Offices"
        ],
        "summary": "Get a single brokerage by OfficeKey",
        "operationId": "OfficesGet",
        "parameters": [
          {
            "name": "officeKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/open-houses": {
      "get": {
        "tags": [
          "Open houses"
        ],
        "summary": "Search upcoming open houses",
        "description": "Returns a paged list of upcoming open houses with their listing details merged in. Default window is today through 30 days from now; override with `from` / `to` ISO date params.",
        "operationId": "OpenHousesSearch",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stateOrProvince",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listAgentKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listOfficeKey",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "long",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "double"
            }
          },
          {
            "name": "pageNum",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "resultsPerPage",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Attribution": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "nullable": true
          },
          "statement": {
            "type": "string",
            "nullable": true
          },
          "logoUrl": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ListingLegal": {
        "type": "object",
        "properties": {
          "logoUrl": {
            "type": "string",
            "nullable": true
          },
          "poweredByLabel": {
            "type": "string",
            "nullable": true
          },
          "disclaimer": {
            "type": "string",
            "nullable": true
          },
          "trademarkText": {
            "type": "string",
            "nullable": true
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "dataProvider": {
            "type": "string",
            "nullable": true
          },
          "presenter": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ListingSummary": {
        "type": "object",
        "properties": {
          "listingKey": {
            "type": "string",
            "nullable": true
          },
          "mlsNumber": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "listPrice": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "leaseAmount": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "totalActualRent": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "leaseAmountFrequency": {
            "type": "string",
            "nullable": true
          },
          "transactionType": {
            "type": "string",
            "nullable": true
          },
          "bedrooms": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "bathrooms": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "livingAreaSqft": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "yearBuilt": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "propertyType": {
            "type": "string",
            "nullable": true
          },
          "propertySubType": {
            "type": "string",
            "nullable": true
          },
          "commonInterest": {
            "type": "string",
            "nullable": true
          },
          "addressLine": {
            "type": "string",
            "nullable": true
          },
          "unitNumber": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "stateOrProvince": {
            "type": "string",
            "nullable": true
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "publicRemarksExcerpt": {
            "type": "string",
            "nullable": true
          },
          "primaryImageUrl": {
            "type": "string",
            "nullable": true
          },
          "photoCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "virtualTourUrl": {
            "type": "string",
            "nullable": true
          },
          "videoUrl": {
            "type": "string",
            "nullable": true
          },
          "listAgentKey": {
            "type": "string",
            "nullable": true
          },
          "listAgentFullName": {
            "type": "string",
            "nullable": true
          },
          "listOfficeKey": {
            "type": "string",
            "nullable": true
          },
          "listOfficeName": {
            "type": "string",
            "nullable": true
          },
          "modificationTimestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ListingSummarySearchResponse": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "resultsPerPage": {
            "type": "integer",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "format": "int32"
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListingSummary"
            },
            "nullable": true
          },
          "attribution": {
            "$ref": "#/components/schemas/Attribution"
          },
          "legal": {
            "$ref": "#/components/schemas/ListingLegal"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "API key issued from the portal — pass as the X-API-KEY header on every request.",
        "name": "X-API-KEY",
        "in": "header"
      },
      "CognitoJwt": {
        "type": "http",
        "description": "Cognito ID token — only required for /portal/* endpoints used by the customer portal.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ]
}