---
openapi: 3.0.0
info:
  title: Cloud CMA API
  description: |-
    Cloud CMA allows real estate agents to easily create custom CMA, Buyer Tour, and Property Reports. In order to enable this functionality to be embedded in other web sites, especially MLS sites, we have made an API publicly available. Using simple links or AJAX techniques, you can send listings (via MLS numbers) to Cloud CMA and kick off the desired report. Users can continue on your site without interruption while reports are being generated.

    ## How the API Works

    You can send the listings your user has currently selected, in the form of their MLS numbers, to Cloud CMA and initiate report creation. You can also use AJAX techniques to:
    - Send desired MLS numbers to Cloud CMA
    - Receive immediate feedback on success or failure
    - Allow the user to continue on your site without interruption
    - Track report status and delivery via webhooks

    ## Authentication

    Cloud CMA is a subscription-based service and requires an ID and password to use. There are two authentication approaches:

    **1. Session-Based (Automatic)**
    - All uses of the API will work immediately if the user is already logged into a Cloud CMA session
    - If a current session does not exist, Cloud CMA will handle the authentication by requesting the user log in first
    - After login, Cloud CMA automatically routes them to the requested page
    - Ideal for MLS integration where users are already authenticated

    **2. API Key-Based**
    - Use an API key from your Cloud CMA account (Settings > API or Account Settings > Integrations)
    - Pass the api_key parameter with each request
    - Ideal for server-to-server calls and lead capture forms

    ## Getting Trial Access

    Developers who need a trial ID and password can request one from Cloud CMA support at developers@cloudcma.com

    ## What You Can Build

    **Report Creation:** Agents can create CMAs, Buyer Tours, Property Reports, and Flyers with one or more MLS listings in a single API call.

    **Lead Generation:** Embed quick CMA forms or property report requests on your website. Capture consumer information and automatically generate branded reports.

    **Automated Campaigns:** Set up Homebeat market update automations that send periodic updates (monthly, quarterly, annually) to leads showing comparable sales trends.

    **Flexible Delivery:** Reports can be emailed directly to consumers by Cloud CMA, or delivered via webhook to your system for custom handling.

    ## Architecture

    Cloud CMA performs real-time queries to the MLS RETS server at the moment users request reports. No data replication is required. This ensures:
    - Always current MLS data
    - Better security (no full MLS database stored on Cloud CMA servers)
    - Reduced server load (only querying small subsets of data needed for each report)

    ## Extensibility

    More functionality of Cloud CMA can be exposed pretty easily using standard RESTful web services. Send your suggestions to developers@cloudcma.com
  version: 1.0.0
  contact:
    name: Cloud CMA Developers
    email: developers@cloudcma.com
servers:
- url: https://cloudcma.com
  description: Production API
paths:
  "/docs/mls-security":
    get:
      tags:
      - Documentation
      summary: MLS Security Methods
      description: |-
        Cloud CMA supports four security methods to ensure only valid, active MLS members access listing data via RETS integration.

        ## Method 1: User RETS Credentials
        Users provide their individual MLS RETS credentials. Cloud CMA stores credentials using RSA public key encryption and uses them to authenticate directly with the RETS server.
        - **Pro:** MLS has complete control; users can be deactivated immediately via normal MLS workflow
        - **Con:** Not all MLSs have RETS credentials set up for every member; manual setup may be required

        ## Method 2: MLS RETS Credentials + Agent Verification
        MLS provides Cloud CMA with RETS credentials. When users query data, Cloud CMA logs in with MLS credentials, then verifies the user exists and is active by querying the Agent/User table against their credentials.
        - **Pro:** MLS has complete control; users deactivated immediately
        - **Con:** MLS must allow querying on password field or return active member status

        ## Method 3: Single Sign-On (SSO)
        Users cannot log in directly at cloudcma.com. Instead, they log into their MLS system first, then access Cloud CMA via SSO link. Two options available:
        - **Custom SSO:** Parameters passed in URL (MLS code, user ID, secure hash, timestamp)
        - **SAML:** Cloud CMA is SAML certified and supports standard SAML providers
        - **Pro:** MLS controls both access to MLS and Cloud CMA; deepest integration with MLS systems
        - **Con:** MLS must set up the link/integration within their system

        ## Method 4: Synchronized Agent Table
        Cloud CMA maintains a synchronized table of currently active agents from the MLS. Users provide credentials which are verified against this table on each query.
        - **Pro:** MLS has complete control; users deactivated immediately via normal workflow
        - **Con:** Requires maintaining synchronized agent data

        All methods ensure that only valid, active MLS members can access listing data through Cloud CMA.
      operationId: mlsSecurityMethods
      responses:
        '200':
          description: MLS Security Methods documentation
  "/docs/rets-queries":
    get:
      tags:
      - Documentation
      summary: Cloud CMA RETS Queries
      description: |-
        Cloud CMA does NOT download and maintain the entire MLS database. Instead, it performs real-time RETS queries at the moment users request reports. This provides better security (no full MLS replication) and reduces server load.

        ## Three Query Types

        ### 1. MLS Number Search
        Simplest query type. Single or multiple MLS numbers at a time.
        - Example: Query MLS #12345 and #12346
        - Straightforward RETS DMQL syntax
        - Very efficient

        ### 2. Address Search
        Query by street address. Cloud CMA breaks address into components (street number, street name, city, state, zip).
        - Example: 123 Main St, Huntington Beach, CA
        - Also straightforward DMQL
        - Address less accurate than MLS number due to MLS data entry typos

        ### 3. Latitude/Longitude Range Search
        Most complex query type. Creates rectangular proximity search area around subject property using lat/lon ranges.
        - Example: Search all listings within lat range 44.866-44.868 and lon range -92.590--92.588
        - More useful for finding comparables but can stress RETS servers

        ## Common RETS Server Issues & Solutions

        ### Issue 1: Latitude/Longitude Not Indexed
        Problem: Lat/lon fields on some RETS servers are not indexed, causing slow or failed queries even though they're simple decimal values.

        Solution: Request MLS add an indexed field or create a view with indexed lat/lon support.

        ### Issue 2: Double Negative Syntax Breaks Parser
        Problem: U.S. longitude is negative. Range queries with negative numbers create this DMQL syntax:
        ```
        (LONGITUDE=-92.590--92.588),(LATITUDE=44.866-44.868)
        ```
        The double negative `--` can break some RETS parsers.

        Solution: Create new field `ABSLONGITUDE` containing absolute value of longitude:
        ```
        (ABSLONGITUDE=92.588-92.590),(LATITUDE=44.866-44.868)
        ```
        Then flag Cloud CMA to query the ABSLONGITUDE field instead. This is typically easy to implement and solves the parser issue.

        ## Efficiency Notes
        - Cloud CMA queries only small subsets of MLS daily (10-30 listings per CMA/Buyer Tour, 1 per Property Report)
        - Real-time queries are more secure than replication
        - Proper indexing on RETS servers is critical for performance
      operationId: retsQueries
      responses:
        '200':
          description: RETS Queries documentation
  "/docs/error-handling":
    get:
      tags:
      - Documentation
      summary: Error Handling & Troubleshooting
      description: |-
        ## Common API Errors

        ### Authentication Errors
        **Error:** "You need to sign in or sign up before continuing"
        - **Cause:** Missing api_key parameter
        - **Solution:** Include api_key from Cloud CMA Settings > API (or Account Settings > Integrations)

        **Error:** "User with api_key not found"
        - **Cause:** Invalid or expired API key
        - **Solution:** Verify API key in Cloud CMA account settings; regenerate if needed

        ### Resource Not Found Errors
        **Error:** "No matching listings were found on the MLS"
        - **Cause:** Address is outside the MLS's operating boundary (e.g., subject property in Florida but user's MLS is California)
        - **Solution:** Verify address is within the MLS service area; use MLS numbers when available instead of addresses

        **Error:** Property address returns no results
        - **Cause:** Address mistyped or not found in MLS database
        - **Solution:** Use MLS number instead of address; verify spelling and format

        ### Feature/Permission Errors
        **Error:** "This user does not have the Homebeat feature"
        - **Cause:** Homebeat add-on is not enabled for this user or not available in this MLS
        - **Solution:** Contact Cloud CMA support to enable Homebeat; verify it's available in your MLS

        **Error:** "Frequency is not a valid option"
        - **Cause:** Invalid frequency value provided for Homebeat
        - **Solution:** Use one of the valid frequencies: monthly, quarterly, semi-annually, annually, never

        ### Homebeat Specific Issues
        **Issue:** Welcome email not sent or subscription not active
        - **Check:** Verify lead email address is valid and opted in
        - **Check:** Confirm Homebeat feature is enabled for the user account
        - **Check:** If using custom callback, ensure callback_url is accessible and returning 200 OK

        **Issue:** Homebeat report shows no view counts
        - **Cause:** Report may be too new or leads haven't viewed it yet
        - **Solution:** Wait for updates according to the frequency (monthly, quarterly, etc.)

        ### Webhook Issues
        **Webhooks not being called:**
        - Verify callback_url is publicly accessible (not localhost)
        - Ensure your endpoint returns HTTP 200 within 30 seconds
        - Check server logs for incoming POST requests
        - Cloud CMA will retry failed webhooks multiple times before giving up

        **Webhook Payload Issues:**
        - Verify you're parsing the JSON payload correctly
        - All webhook payloads include: id, user_id, type, title, notes, mls_code, created_at, updated_at, deleted_at, edit_url, pdf_url, action, and job_id (if provided)

        ## Report Generation Issues
        **Report takes longer than expected:**
        - First report generation may take 1-2 minutes as Cloud CMA queries RETS and generates PDF
        - Subsequent reports typically faster due to caching
        - Check webhook callback for completion status

        **PDF URL not working:**
        - PDF URLs are temporarily available (typically 24-48 hours)
        - For permanent storage, download PDF immediately after notification
        - For permanent access, use edit_url to view in Cloud CMA interface

        ## Best Practices
        1. Always use MLS numbers instead of addresses when available (more accurate, faster queries)
        2. Implement webhook callbacks to track report status and delivery
        3. Use job_id parameter to correlate callbacks with your internal systems
        4. Handle webhook retries gracefully
        5. Store pdf_url values immediately upon receipt; don't rely on them being available later
        6. For lead captures, validate email addresses before submission
      operationId: errorHandling
      responses:
        '200':
          description: Error Handling & Troubleshooting guide
  "/docs/webhooks":
    get:
      tags:
      - Documentation
      summary: Webhooks & Callbacks
      description: |-
        Webhooks allow you to receive real-time notifications when reports are created, updated, or deleted. This is useful for tracking report status, integrating with your CRM, and automating lead management.

        ## How Webhooks Work
        1. Include `callback_url` parameter in your API request
        2. Cloud CMA creates the report
        3. When the report status changes (created, updated, deleted), Cloud CMA POSTs to your callback URL
        4. Your system processes the webhook and takes action (send email, log to CRM, etc.)

        ## Optional Parameters
        - `callback_url` (optional): URL where Cloud CMA will POST webhook updates
        - `job_id` (optional): Your unique tracking ID that will be included in all webhook payloads for this report

        ## Webhook Payload Format
        Cloud CMA POSTs JSON to your callback_url:
        ```json
        {
          "id": 12345,
          "user_id": 67890,
          "type": "Cma",
          "title": "The Robertsons",
          "notes": "",
          "mls_code": "crmls",
          "created_at": "2015-07-21T18:04:24Z",
          "updated_at": "2015-07-21T18:04:24Z",
          "deleted_at": null,
          "edit_url": "https://cloudcma.com/cmas/12345/edit",
          "pdf_url": "https://cloudcma.com/pdf/f6f280a379b61c88e9bb68c6f996d501",
          "action": "update",
          "job_id": "your-tracking-id"
        }
        ```

        ## Webhook Actions
        - `create`: Report was just created
        - `update`: Report was updated (usually when PDF is ready)
        - `delete`: Report was deleted

        ## Implementation Requirements
        1. Your endpoint must return HTTP 200 within 30 seconds
        2. Your endpoint should be publicly accessible (not localhost or private network)
        3. Use HTTPS when possible
        4. Cloud CMA will retry failed webhooks automatically (several attempts with backoff)
        5. Store the job_id and pdf_url immediately for permanent reference

        ## Use Cases
        ### Scenario 1: Cloud CMA Handles Email
        Don't provide `job_id`, provide `callback_url`. Cloud CMA creates report and:
        - Sends email to consumer with report link
        - POSTs webhook to your callback_url when report is ready
        - You log the report in your system for tracking

        ### Scenario 2: Your System Handles Email
        Provide both `callback_url` and `job_id`, but don't provide consumer email. Cloud CMA creates report and:
        - POSTs webhook to your callback_url with pdf_url
        - Your system uses job_id to look up which consumer requested it
        - Your system sends custom-formatted email with your branding

        ### Scenario 3: Homebeat Tracking
        For Homebeat automations with `callback_url`, Cloud CMA:
        - POSTs on each frequency update (monthly, quarterly, etc.)
        - Includes pdf_url for each update
        - Allows you to track view counts and engagement
        - If no consumer email provided, you handle all email delivery
      operationId: webhooks
      responses:
        '200':
          description: Webhooks documentation
  "/cmas/new":
    get:
      tags:
      - Report Creation - Agent APIs
      summary: Create a new CMA
      description: Create a new Comparative Market Analysis report with one or more
        MLS listings. Can be initiated directly from an MLS site or broker website.
      operationId: createCMA
      parameters:
      - name: mlsnums
        in: query
        description: Comma-separated list of MLS numbers for subject properties in
          the CMA
        schema:
          type: string
        example: '12345,12346,12347'
      - name: address
        in: query
        description: Single address for the subject property. Used for geocoding to
          set proximity search area.
        schema:
          type: string
        example: 123 Main St, Huntington Beach, CA
      - name: title
        in: query
        description: Title for the CMA report. User can edit in Cloud CMA if not provided.
        schema:
          type: string
        example: The Smith Family
      - name: notes
        in: query
        description: Internal notes for the report. Agents see these, consumers do
          not.
        schema:
          type: string
        example: Initiated from your MLS
      - name: beds
        in: query
        description: Bedrooms of subject property. Used to filter comparable properties.
        schema:
          type: integer
      - name: baths
        in: query
        description: Bathrooms of subject property. Used to filter comparable properties.
        schema:
          type: number
      - name: sqft
        in: query
        description: Square feet of subject property. Used to filter comparable properties.
        schema:
          type: integer
      - name: prop_type
        in: query
        description: Property type for proximity search filter (e.g., RES, Commercial).
          Must match MLS RETS metadata.
        schema:
          type: string
      - name: min_listings
        in: query
        description: Minimum number of comparable listings to include. Default varies
          by MLS.
        schema:
          type: integer
      - name: lat
        in: query
        description: Override geocoded latitude for proximity search center point
        schema:
          type: number
          format: double
      - name: lon
        in: query
        description: Override geocoded longitude for proximity search center point
        schema:
          type: number
          format: double
      - name: callback_url
        in: query
        description: Webhook URL for report status updates. See Webhooks section.
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to Cloud CMA report creation page. User logged in
            → goes directly to new CMA. User not logged in → sent to login first.
        '400':
          description: Invalid parameters (e.g., invalid MLS numbers, address outside
            MLS boundary)
    post:
      tags:
      - Report Creation - Agent APIs
      summary: Create a new CMA (POST)
      description: Create a new CMA using POST method. Same parameters as GET.
      operationId: createCMAPost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              "$ref": "#/components/schemas/CMACreateRequest"
      responses:
        '302':
          description: Redirect to Cloud CMA report creation
  "/tours/new":
    get:
      tags:
      - Report Creation - Agent APIs
      summary: Create a new Buyer Tour
      description: Create a Buyer Tour report showcasing multiple properties to a
        potential buyer.
      operationId: createBuyerTour
      parameters:
      - name: mlsnums
        in: query
        description: Comma-separated list of MLS numbers for properties in the tour
        schema:
          type: string
        required: true
      - name: title
        in: query
        description: Title for the Buyer Tour
        schema:
          type: string
      - name: notes
        in: query
        description: Internal notes for the tour
        schema:
          type: string
      - name: callback_url
        in: query
        description: Webhook URL for tour status updates
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to Cloud CMA Buyer Tour creation
  "/properties/new":
    get:
      tags:
      - Report Creation - Agent APIs
      summary: Create a new Property Report
      description: Create a single-property detailed report. Can be initiated by MLS
        number or address.
      operationId: createPropertyReport
      parameters:
      - name: mlsnums
        in: query
        description: MLS number of the subject property (single only)
        schema:
          type: string
      - name: address
        in: query
        description: Address of the subject property. Less accurate than MLS number.
        schema:
          type: string
        example: 123 Main Street, Costa Mesa, CA 92626
      - name: title
        in: query
        description: Title for the report
        schema:
          type: string
      - name: notes
        in: query
        description: Internal notes
        schema:
          type: string
      - name: callback_url
        in: query
        description: Webhook URL for report status updates
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to Cloud CMA Property Report creation
  "/flyers/new":
    get:
      tags:
      - Report Creation - Agent APIs
      summary: Create a new Flyer
      description: Create a property flyer for a single listing.
      operationId: createFlyer
      parameters:
      - name: mlsnums
        in: query
        description: MLS number of the property
        schema:
          type: string
      - name: address
        in: query
        description: Address of the property
        schema:
          type: string
      - name: title
        in: query
        description: Flyer title
        schema:
          type: string
      - name: notes
        in: query
        description: Internal notes
        schema:
          type: string
      - name: callback_url
        in: query
        description: Webhook URL for status updates
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to Cloud CMA Flyer creation
  "/cmas/widget":
    get:
      tags:
      - Lead Generation - Widget APIs
      summary: Create and deliver Quick CMA for lead
      description: Consumer-facing API to create a Quick CMA from website lead form,
        automatically branded to agent, and email to consumer. Captures lead data
        for agent tracking.
      operationId: quickCMAWidget
      parameters:
      - name: api_key
        in: query
        description: Cloud CMA API key for the user (from Settings > API)
        schema:
          type: string
        required: true
      - name: name
        in: query
        description: Consumer's full name
        schema:
          type: string
      - name: email_to
        in: query
        description: Consumer's email address for report delivery
        schema:
          type: string
          format: email
        required: true
      - name: address
        in: query
        description: Consumer's subject property address
        schema:
          type: string
        required: true
      - name: sqft
        in: query
        description: Square feet of subject property
        schema:
          type: integer
      - name: beds
        in: query
        description: Bedrooms
        schema:
          type: integer
      - name: baths
        in: query
        description: Bathrooms
        schema:
          type: number
      - name: prop_type
        in: query
        description: Property type to restrict comparable search
        schema:
          type: string
      - name: title
        in: query
        description: 'Report title. Default: consumer''s name or email.'
        schema:
          type: string
      - name: headline
        in: query
        description: 'Cover page headline. Default: ''Quick CMA'''
        schema:
          type: string
      - name: min_listings
        in: query
        description: 'Minimum comparable listings. Default: 10'
        schema:
          type: integer
          default: 10
      - name: months_back
        in: query
        description: 'Historical period for comparables. Default: 12 months'
        schema:
          type: integer
          default: 12
      - name: email_subject
        in: query
        description: Email subject line
        schema:
          type: string
      - name: email_msg
        in: query
        description: 'Email message body. Default: just the report link.'
        schema:
          type: string
      - name: template
        in: query
        description: 'Report template. Default: ''Web Leads''. Must exist in user''s
          account.'
        schema:
          type: string
      - name: job_id
        in: query
        description: Unique ID to track in callback (for webhook integration)
        schema:
          type: string
      - name: callback_url
        in: query
        description: Webhook URL called when report is ready. Receives pdf_url and
          job_id.
        schema:
          type: string
          format: uri
      responses:
        '200':
          description: Quick CMA created and queued for delivery
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/QuickCMAResponse"
        '400':
          description: Invalid API key or missing required parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      tags:
      - Lead Generation - Widget APIs
      summary: Create and deliver Quick CMA (POST)
      description: POST version of Quick CMA widget endpoint
      operationId: quickCMAWidgetPost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              "$ref": "#/components/schemas/QuickCMARequest"
      responses:
        '200':
          description: Quick CMA created successfully
        '400':
          description: Error creating Quick CMA
  "/properties/widget":
    get:
      tags:
      - Lead Generation - Widget APIs
      summary: Create Property Report for email delivery
      description: Consumer requests a Property Report for the property they're viewing.
        Cloud CMA creates and emails the PDF to the consumer.
      operationId: propertyReportWidget
      parameters:
      - name: api_key
        in: query
        description: Cloud CMA API key (required)
        schema:
          type: string
        required: true
      - name: mlsnum
        in: query
        description: MLS number of the subject property (required if address not provided)
        schema:
          type: string
      - name: address
        in: query
        description: Address of the subject property (less accurate than MLS number)
        schema:
          type: string
      - name: email_to
        in: query
        description: Consumer email for report delivery (required)
        schema:
          type: string
          format: email
        required: true
      - name: email_subject
        in: query
        description: 'Email subject. Default: ''Your Cloud CMA Property Report'''
        schema:
          type: string
      - name: email_msg
        in: query
        description: 'Email message body. Default: just the report link.'
        schema:
          type: string
      - name: theme
        in: query
        description: 'Report theme. Default: broker''s last used theme.'
        schema:
          type: string
      - name: title
        in: query
        description: 'Report title shown on cover (''Prepared for'' section). Default:
          email_to.'
        schema:
          type: string
      - name: notes
        in: query
        description: Internal notes (consumer never sees)
        schema:
          type: string
      - name: callback_url
        in: query
        description: Webhook URL. If provided with job_id, you handle email delivery
          instead of Cloud CMA.
        schema:
          type: string
          format: uri
      - name: job_id
        in: query
        description: Unique tracking ID for webhook callbacks
        schema:
          type: string
      responses:
        '200':
          description: Property Report created successfully
        '400':
          description: Invalid parameters or property not found
    post:
      tags:
      - Lead Generation - Widget APIs
      summary: Create Property Report for email delivery (POST)
      operationId: propertyReportWidgetPost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              "$ref": "#/components/schemas/PropertyReportRequest"
      responses:
        '200':
          description: Property Report created and queued
  "/homebeats/widget":
    get:
      tags:
      - Homebeat Automation
      summary: Get Homebeat metadata
      description: Retrieve metadata about Homebeat feature availability, MLS property
        types, and supported frequencies for a user.
      operationId: getHomebeatMetadata
      parameters:
      - name: api_key
        in: query
        description: Cloud CMA API key (from Account Settings > Integrations)
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Homebeat metadata
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HomebeatMetadata"
        '400':
          description: Invalid API key or user not found
    post:
      tags:
      - Homebeat Automation
      summary: Create new Homebeat automation
      description: Create an automated Homebeat that sends market updates to leads
        at specified frequency (monthly, quarterly, etc). Can email leads directly
        or use webhook for custom delivery.
      operationId: createHomebeat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/HomebeatCreateRequest"
      responses:
        '201':
          description: Homebeat created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HomebeatCreateResponse"
        '400':
          description: Invalid request or user does not have Homebeat feature
  "/homebeats/report":
    get:
      tags:
      - Homebeat Automation
      summary: Get Homebeat report
      description: Download a report of all created Homebeats with view counts in
        CSV or JSON format.
      operationId: getHomebeatReport
      parameters:
      - name: api_key
        in: query
        description: Cloud CMA API key (optional - defaults to current logged-in user
          if omitted)
        schema:
          type: string
      - name: Accept
        in: header
        description: 'Response format: text/csv or application/json'
        schema:
          type: string
          enum:
          - text/csv
          - application/json
      responses:
        '200':
          description: Homebeat report data
          content:
            text/csv:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/HomebeatReportItem"
components:
  schemas:
    CMACreateRequest:
      type: object
      properties:
        mlsnums:
          type: string
          description: Comma-separated MLS numbers
        address:
          type: string
          description: Subject property address
        title:
          type: string
        notes:
          type: string
        beds:
          type: integer
        baths:
          type: number
        sqft:
          type: integer
        prop_type:
          type: string
        min_listings:
          type: integer
        lat:
          type: number
          format: double
        lon:
          type: number
          format: double
        callback_url:
          type: string
          format: uri
    QuickCMARequest:
      type: object
      required:
      - api_key
      - email_to
      - address
      properties:
        api_key:
          type: string
        name:
          type: string
        email_to:
          type: string
          format: email
        address:
          type: string
        sqft:
          type: integer
        beds:
          type: integer
        baths:
          type: number
        prop_type:
          type: string
        title:
          type: string
        headline:
          type: string
        min_listings:
          type: integer
        months_back:
          type: integer
        email_subject:
          type: string
        email_msg:
          type: string
        template:
          type: string
        job_id:
          type: string
        callback_url:
          type: string
          format: uri
    PropertyReportRequest:
      type: object
      required:
      - api_key
      - email_to
      properties:
        api_key:
          type: string
        mlsnum:
          type: string
        address:
          type: string
        email_to:
          type: string
          format: email
        email_subject:
          type: string
        email_msg:
          type: string
        theme:
          type: string
        title:
          type: string
        notes:
          type: string
        callback_url:
          type: string
          format: uri
        job_id:
          type: string
    QuickCMAResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
        job_id:
          type: string
        pdf_url:
          type: string
          format: uri
          description: URL to download the generated PDF
        email_sent:
          type: boolean
    HomebeatMetadata:
      type: object
      properties:
        user:
          type: object
          properties:
            id:
              type: integer
            api_key:
              type: string
        mls:
          type: object
          properties:
            code:
              type: string
              description: MLS code identifier
            title:
              type: string
              description: Full MLS name
            prop_types:
              type: array
              items:
                type: string
              description: Property types available in this MLS
            default_prop_type:
              type: string
        homebeat:
          type: object
          properties:
            has_feature:
              type: boolean
              description: Whether user has Homebeat add-on enabled
            frequencies:
              type: array
              items:
                type: string
                enum:
                - monthly
                - quarterly
                - semi-annually
                - annually
                - never
              description: Supported update frequencies
    HomebeatCreateRequest:
      type: object
      required:
      - automation
      properties:
        automation:
          type: object
          required:
          - api_key
          - frequency
          - subject_property
          - lead
          properties:
            api_key:
              type: string
            frequency:
              type: string
              enum:
              - monthly
              - quarterly
              - semi-annually
              - annually
              - never
              description: How often to send Homebeat updates
            welcome_email:
              type: boolean
              default: true
              description: Send double opt-in welcome email
            report:
              type: object
              properties:
                prop_type:
                  type: string
                  nullable: true
                  description: Filter comparables to property type. Null = use MLS
                    default.
                callback_url:
                  type: string
                  format: uri
                  nullable: true
                  description: Webhook URL for Homebeat updates
            subject_property:
              type: object
              properties:
                address:
                  type: string
                geo_lat:
                  type: number
                  nullable: true
                geo_lon:
                  type: number
                  nullable: true
                sqft:
                  type: string
                beds:
                  type: string
                baths:
                  type: string
                garages:
                  type: string
                  nullable: true
                lot_size:
                  type: string
                  nullable: true
                taxes:
                  type: string
                  nullable: true
            lead:
              type: object
              properties:
                name:
                  type: string
                email_address:
                  type: string
                  format: email
                phone:
                  type: string
    HomebeatCreateResponse:
      type: object
      properties:
        id:
          type: integer
          description: Homebeat record ID
        status:
          type: string
          enum:
          - created
          - error
        error:
          type: string
          description: Error message if creation failed
        first_report_sent:
          type: boolean
    HomebeatReportItem:
      type: object
      properties:
        id:
          type: integer
        lead_name:
          type: string
        lead_email:
          type: string
        subject_address:
          type: string
        frequency:
          type: string
        created_at:
          type: string
          format: date-time
        view_count:
          type: integer
    WebhookPayload:
      type: object
      description: Webhook callback payload sent to callback_url
      properties:
        id:
          type: integer
          description: Report ID
        user_id:
          type: integer
          description: Cloud CMA user ID
        type:
          type: string
          enum:
          - Cma
          - BuyerTour
          - PropertyReport
          - Flyer
          description: Report type
        title:
          type: string
        notes:
          type: string
        mls_code:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
        edit_url:
          type: string
          format: uri
          description: Link to edit report in Cloud CMA
        pdf_url:
          type: string
          format: uri
          description: Link to download PDF
        action:
          type: string
          enum:
          - create
          - update
          - delete
          description: What triggered the webhook
        job_id:
          type: string
          description: Your tracking ID from callback_url parameter
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: Cloud CMA API key from Settings > API (or Account Settings > Integrations)
security:
- ApiKey: []
tags:
- name: Report Creation - Agent APIs
  description: APIs for agents to create CMAs, Buyer Tours, Property Reports, and
    Flyers. Can redirect user to Cloud CMA UI or trigger report generation.
- name: Lead Generation - Widget APIs
  description: Consumer-facing APIs for capturing leads via website forms. Creates
    reports and manages email delivery with optional webhook callbacks for custom
    handling.
- name: Homebeat Automation
  description: Automated market update campaigns sent to leads at specified frequency.
    Includes metadata retrieval, creation, and reporting.
- name: Documentation
  description: Comprehensive guides covering MLS security methods, RETS query types,
    webhooks, error handling, and best practices.
