Realtor.com Connections Plus API

asyncapi: 2.6.0
info:
  title: Realtor.com Connections Plus Events
  description: >-
    The Realtor.com Connections Plus API provides a direct connection between
    the Realtor.com lead delivery system and supporting CRM platforms. It
    enables real estate agents, brokers, and offices to receive buyer and
    seller leads in real time via HTTPS POST rather than email. The API
    delivers richer lead data including listing URLs, geographic coordinates,
    dates, and MLS information that are not available through standard email
    delivery. It uses HTTPS for secure transmission and supports optional
    digital signatures for data verification.
  version: '1.0'
  contact:
    name: Realtor.com Support
    url: https://www.realtor.com/marketing/connections/
servers:
  crmEndpoint:
    url: '{crmEndpointUrl}'
    protocol: https
    description: >-
      CRM endpoint URL configured by the customer in the Realtor.com dashboard
      to receive lead delivery POST requests from Realtor.com.
    variables:
      crmEndpointUrl:
        description: >-
          The URL of the CRM endpoint that will receive lead data.
    security:
      - apiKey: []
channels:
  /lead:
    description: >-
      Channel for receiving real-time lead deliveries from Realtor.com
      Connections Plus. Leads are pushed to the configured CRM endpoint via
      HTTPS POST when a buyer or seller expresses interest through Realtor.com.
    publish:
      operationId: receiveConnectionsPlusLead
      summary: Receive a Connections Plus lead
      description: >-
        Delivers a lead from the Realtor.com Connections Plus system to the
        configured CRM endpoint. Each lead includes contact information for
        the buyer or seller, the property they expressed interest in, and
        metadata about the lead source. Leads may include optional digital
        signatures for verification.
      message:
        oneOf:
          - $ref: '#/components/messages/BuyerLead'
          - $ref: '#/components/messages/SellerLead'
components:
  securitySchemes:
    apiKey:
      type: httpApiKey
      name: X-API-Key
      in: header
      description: >-
        API key configured in the Realtor.com dashboard for authenticating
        lead delivery requests.
    digitalSignature:
      type: httpApiKey
      name: X-Signature
      in: header
      description: >-
        Optional digital signature header for verifying the authenticity and
        integrity of lead delivery payloads.
  messages:
    BuyerLead:
      name: BuyerLead
      title: Buyer Lead
      summary: >-
        Lead from a potential buyer who expressed interest in a property listing
        on Realtor.com.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BuyerLeadPayload'
    SellerLead:
      name: SellerLead
      title: Seller Lead
      summary: >-
        Lead from a potential seller who is seeking representation for selling
        their property.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SellerLeadPayload'
  schemas:
    BuyerLeadPayload:
      type: object
      description: >-
        Payload containing buyer lead information delivered from Realtor.com
        Connections Plus.
      required:
        - lead_id
        - role
        - contact
        - timestamp
      properties:
        lead_id:
          type: string
          description: >-
            Unique identifier for the lead.
        role:
          type: string
          description: >-
            Role of the lead, always buyer for this message type.
          enum:
            - buyer
        contact:
          $ref: '#/components/schemas/LeadContact'
        property:
          $ref: '#/components/schemas/LeadProperty'
        finance_info:
          $ref: '#/components/schemas/FinanceInfo'
        source:
          type: string
          description: >-
            Source of the lead on Realtor.com such as listing page,
            search results, or recommendation.
        message:
          type: string
          description: >-
            Optional message from the buyer expressing their interest
            or asking questions about the property.
        is_likely_to_transact:
          type: boolean
          description: >-
            Indicator of whether the lead is likely to complete a transaction.
        probability_to_transact:
          type: number
          description: >-
            Probability score from 0 to 1 indicating how likely the lead is
            to complete a transaction.
          minimum: 0
          maximum: 1
        timestamp:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp when the lead was generated.
        digital_signature:
          type: string
          description: >-
            Optional digital signature for verifying the lead data integrity.
    SellerLeadPayload:
      type: object
      description: >-
        Payload containing seller lead information delivered from Realtor.com
        Connections Plus.
      required:
        - lead_id
        - role
        - contact
        - timestamp
      properties:
        lead_id:
          type: string
          description: >-
            Unique identifier for the lead.
        role:
          type: string
          description: >-
            Role of the lead, always seller for this message type.
          enum:
            - seller
        contact:
          $ref: '#/components/schemas/LeadContact'
        property:
          $ref: '#/components/schemas/SellerProperty'
        source:
          type: string
          description: >-
            Source of the lead on Realtor.com.
        message:
          type: string
          description: >-
            Optional message from the seller about their needs.
        timestamp:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp when the lead was generated.
        digital_signature:
          type: string
          description: >-
            Optional digital signature for verifying the lead data integrity.
    LeadContact:
      type: object
      description: >-
        Contact information for the lead.
      required:
        - email
      properties:
        first_name:
          type: string
          description: >-
            First name of the lead.
        last_name:
          type: string
          description: >-
            Last name of the lead.
        email:
          type: string
          format: email
          description: >-
            Email address of the lead.
        phone:
          type: string
          description: >-
            Phone number of the lead.
    LeadProperty:
      type: object
      description: >-
        Property information associated with a buyer lead.
      properties:
        listing_url:
          type: string
          format: uri
          description: >-
            URL of the property listing on Realtor.com.
        address:
          type: string
          description: >-
            Full street address of the property.
        city:
          type: string
          description: >-
            City where the property is located.
        state:
          type: string
          description: >-
            State abbreviation where the property is located.
        zip_code:
          type: string
          description: >-
            Five-digit ZIP code of the property.
        latitude:
          type: number
          description: >-
            Latitude coordinate of the property.
        longitude:
          type: number
          description: >-
            Longitude coordinate of the property.
        mls_id:
          type: string
          description: >-
            MLS listing identifier.
        mls_name:
          type: string
          description: >-
            Name of the MLS that holds the listing.
        listing_status:
          type: string
          description: >-
            Current listing status such as active, pending, or sold.
        list_price:
          type: number
          description: >-
            Listing price in dollars.
        beds:
          type: integer
          description: >-
            Number of bedrooms.
        baths:
          type: integer
          description: >-
            Number of bathrooms.
        sqft:
          type: integer
          description: >-
            Interior square footage.
        active_days_on_market:
          type: integer
          description: >-
            Number of days the property has been actively listed.
        listing_agent:
          type: object
          description: >-
            Listing agent contact information.
          properties:
            name:
              type: string
              description: >-
                Full name of the listing agent.
            email:
              type: string
              format: email
              description: >-
                Email address of the listing agent.
            phone:
              type: string
              description: >-
                Phone number of the listing agent.
    SellerProperty:
      type: object
      description: >-
        Property information associated with a seller lead.
      properties:
        address:
          type: string
          description: >-
            Full street address of the property the seller wants to list.
        city:
          type: string
          description: >-
            City where the property is located.
        state:
          type: string
          description: >-
            State abbreviation where the property is located.
        zip_code:
          type: string
          description: >-
            Five-digit ZIP code of the property.
        property_type:
          type: string
          description: >-
            Type of property such as single_family, condo, or townhome.
        estimated_value:
          type: number
          description: >-
            Estimated value of the property in dollars.
    FinanceInfo:
      type: object
      description: >-
        Financial qualification information provided by the buyer.
      properties:
        pre_approved:
          type: boolean
          description: >-
            Whether the buyer is pre-approved for a mortgage.
        budget_min:
          type: number
          description: >-
            Minimum budget in dollars.
        budget_max:
          type: number
          description: >-
            Maximum budget in dollars.
        financing_type:
          type: string
          description: >-
            Type of financing the buyer intends to use such as conventional,
            FHA, VA, or cash.