openapi: 3.1.0
info:
  title: Taylor Morrison Home Search API
  description: >-
    Taylor Morrison Home Corporation's API for searching new home communities, available
    homes, floor plans, and lot inventory. Powers the digital homebuying experience
    including the industry-first fully online to-be-built reservation system.
  version: '1.0'
  contact:
    name: Taylor Morrison
    url: https://www.taylormorrison.com/
externalDocs:
  description: Taylor Morrison Website
  url: https://www.taylormorrison.com/
servers:
  - url: https://www.taylormorrison.com/api
    description: Production
tags:
  - name: Communities
    description: New home community search and details
  - name: Homes
    description: Available homes and inventory
  - name: Floor Plans
    description: Floor plan catalog and options
  - name: Lots
    description: Lot availability and details
  - name: Reservations
    description: Online home reservation and configuration
  - name: Design
    description: Design studio selections and options
security:
  - apiKeyAuth: []
paths:
  /communities:
    get:
      operationId: listCommunities
      summary: List Communities
      description: >-
        Returns a list of active Taylor Morrison communities filtered by state, city,
        metro area, or price range.
      tags:
        - Communities
      security: []
      parameters:
        - name: state
          in: query
          required: false
          description: Two-letter state code filter
          schema:
            type: string
            pattern: "^[A-Z]{2}$"
        - name: city
          in: query
          required: false
          description: City name filter
          schema:
            type: string
        - name: metro
          in: query
          required: false
          description: Metropolitan area name
          schema:
            type: string
        - name: price_min
          in: query
          required: false
          description: Minimum home price
          schema:
            type: integer
        - name: price_max
          in: query
          required: false
          description: Maximum home price
          schema:
            type: integer
        - name: bedrooms
          in: query
          required: false
          description: Minimum number of bedrooms
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          description: Maximum communities to return
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of communities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /communities/{community_id}:
    get:
      operationId: getCommunity
      summary: Get Community
      description: Returns detailed information about a specific Taylor Morrison community.
      tags:
        - Communities
      security: []
      parameters:
        - name: community_id
          in: path
          required: true
          description: Community identifier
          schema:
            type: string
      responses:
        '200':
          description: Community details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Community'
        '404':
          $ref: '#/components/responses/NotFound'
  /homes:
    get:
      operationId: listHomes
      summary: List Available Homes
      description: Returns available homes (move-in ready and to-be-built) across communities.
      tags:
        - Homes
      security: []
      parameters:
        - name: community_id
          in: query
          required: false
          description: Filter by community
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Home availability status
          schema:
            type: string
            enum:
              - available
              - pending
              - model
              - under-construction
              - to-be-built
        - name: bedrooms
          in: query
          required: false
          description: Number of bedrooms
          schema:
            type: integer
        - name: bathrooms
          in: query
          required: false
          description: Number of bathrooms
          schema:
            type: number
        - name: price_min
          in: query
          required: false
          description: Minimum price
          schema:
            type: integer
        - name: price_max
          in: query
          required: false
          description: Maximum price
          schema:
            type: integer
        - name: sqft_min
          in: query
          required: false
          description: Minimum square footage
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          description: Maximum homes to return
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of available homes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomeList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /homes/{home_id}:
    get:
      operationId: getHome
      summary: Get Home Details
      description: Returns full details of a specific home including floor plan, lot, pricing, and availability.
      tags:
        - Homes
      security: []
      parameters:
        - name: home_id
          in: path
          required: true
          description: Home identifier
          schema:
            type: string
      responses:
        '200':
          description: Home details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Home'
        '404':
          $ref: '#/components/responses/NotFound'
  /floor-plans:
    get:
      operationId: listFloorPlans
      summary: List Floor Plans
      description: Returns available floor plans for a community or across all communities.
      tags:
        - Floor Plans
      security: []
      parameters:
        - name: community_id
          in: query
          required: false
          description: Filter by community
          schema:
            type: string
        - name: bedrooms
          in: query
          required: false
          description: Number of bedrooms
          schema:
            type: integer
        - name: bathrooms
          in: query
          required: false
          description: Number of bathrooms
          schema:
            type: number
        - name: sqft_min
          in: query
          required: false
          description: Minimum square footage
          schema:
            type: integer
        - name: sqft_max
          in: query
          required: false
          description: Maximum square footage
          schema:
            type: integer
        - name: stories
          in: query
          required: false
          description: Number of stories
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          description: Maximum floor plans to return
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of floor plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloorPlanList'
  /floor-plans/{plan_id}:
    get:
      operationId: getFloorPlan
      summary: Get Floor Plan
      description: Returns detailed floor plan information including dimensions, rooms, and structural options.
      tags:
        - Floor Plans
      security: []
      parameters:
        - name: plan_id
          in: path
          required: true
          description: Floor plan identifier
          schema:
            type: string
      responses:
        '200':
          description: Floor plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloorPlan'
        '404':
          $ref: '#/components/responses/NotFound'
  /lots:
    get:
      operationId: listLots
      summary: List Available Lots
      description: Returns available lots in a community for to-be-built home construction.
      tags:
        - Lots
      parameters:
        - name: community_id
          in: query
          required: true
          description: Community to list lots for
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Lot availability status
          schema:
            type: string
            enum:
              - available
              - reserved
              - sold
              - hold
      responses:
        '200':
          description: List of lots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LotList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reservations:
    post:
      operationId: createReservation
      summary: Create Reservation
      description: >-
        Submit an online home reservation for a to-be-built or available home with
        initial design selections and a deposit. This powers Taylor Morrison's
        industry-first fully digital homebuying flow.
      tags:
        - Reservations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationRequest'
      responses:
        '201':
          description: Reservation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listReservations
      summary: List Reservations
      description: Returns reservations for the authenticated user.
      tags:
        - Reservations
      responses:
        '200':
          description: List of reservations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reservations/{reservation_id}:
    get:
      operationId: getReservation
      summary: Get Reservation
      description: Returns details of a specific reservation including status and selections.
      tags:
        - Reservations
      parameters:
        - name: reservation_id
          in: path
          required: true
          description: Reservation identifier
          schema:
            type: string
      responses:
        '200':
          description: Reservation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /design/options:
    get:
      operationId: listDesignOptions
      summary: List Design Options
      description: Returns available design selections for a floor plan including structural, exterior, and interior options.
      tags:
        - Design
      parameters:
        - name: plan_id
          in: query
          required: true
          description: Floor plan to get options for
          schema:
            type: string
        - name: category
          in: query
          required: false
          description: Option category filter
          schema:
            type: string
            enum:
              - structural
              - exterior
              - flooring
              - cabinets
              - countertops
              - appliances
              - fixtures
              - lighting
      responses:
        '200':
          description: Design options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignOptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error description
    Community:
      type: object
      properties:
        community_id:
          type: string
          description: Unique community identifier
        name:
          type: string
          description: Community name
        city:
          type: string
          description: City
        state:
          type: string
          description: State code
        metro:
          type: string
          description: Metropolitan area
        price_from:
          type: integer
          description: Starting price for homes in this community
        price_to:
          type: integer
          description: Upper price range for homes in this community
        status:
          type: string
          enum:
            - selling
            - coming-soon
            - sold-out
        home_count:
          type: integer
          description: Number of available homes
        description:
          type: string
          description: Community description
        images:
          type: array
          items:
            type: string
            format: uri
          description: Community image URLs
        amenities:
          type: array
          items:
            type: string
          description: Community amenities
        latitude:
          type: number
        longitude:
          type: number
    CommunityList:
      type: object
      properties:
        communities:
          type: array
          items:
            $ref: '#/components/schemas/Community'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    Home:
      type: object
      properties:
        home_id:
          type: string
          description: Unique home identifier
        community_id:
          type: string
          description: Community this home belongs to
        address:
          type: string
          description: Street address (if available)
        status:
          type: string
          enum:
            - available
            - pending
            - model
            - under-construction
            - to-be-built
        price:
          type: integer
          description: Base price
        bedrooms:
          type: integer
        bathrooms:
          type: number
        sqft:
          type: integer
          description: Square footage
        stories:
          type: integer
        garage:
          type: integer
          description: Number of garage spaces
        floor_plan:
          $ref: '#/components/schemas/FloorPlan'
        images:
          type: array
          items:
            type: string
            format: uri
        virtual_tour_url:
          type: string
          format: uri
          description: 3D virtual tour URL
    HomeList:
      type: object
      properties:
        homes:
          type: array
          items:
            $ref: '#/components/schemas/Home'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    FloorPlan:
      type: object
      properties:
        plan_id:
          type: string
          description: Floor plan identifier
        name:
          type: string
          description: Floor plan name
        bedrooms:
          type: integer
        bathrooms:
          type: number
        sqft_min:
          type: integer
          description: Minimum square footage (base plan)
        sqft_max:
          type: integer
          description: Maximum square footage (with all options)
        stories:
          type: integer
        garage:
          type: integer
        base_price:
          type: integer
          description: Base price for this floor plan
        description:
          type: string
        images:
          type: array
          items:
            type: string
            format: uri
        floor_plan_pdf:
          type: string
          format: uri
          description: PDF floor plan download URL
    FloorPlanList:
      type: object
      properties:
        floor_plans:
          type: array
          items:
            $ref: '#/components/schemas/FloorPlan'
        total:
          type: integer
    Lot:
      type: object
      properties:
        lot_id:
          type: string
        lot_number:
          type: string
          description: Lot number in the community plat
        status:
          type: string
          enum:
            - available
            - reserved
            - sold
            - hold
        price_premium:
          type: integer
          description: Lot premium above base price
        sqft:
          type: integer
          description: Lot size in square feet
        dimensions:
          type: string
          description: Lot dimensions (e.g., "60x120")
        backing:
          type: string
          description: What the lot backs to (greenbelt, pond, etc.)
    LotList:
      type: object
      properties:
        lots:
          type: array
          items:
            $ref: '#/components/schemas/Lot'
        total:
          type: integer
    ReservationRequest:
      type: object
      required:
        - community_id
        - plan_id
        - buyer_info
        - deposit
      properties:
        community_id:
          type: string
          description: Community ID
        plan_id:
          type: string
          description: Floor plan ID
        lot_id:
          type: string
          description: Lot ID (for to-be-built)
        home_id:
          type: string
          description: Home ID (for available/quick-move-in)
        buyer_info:
          type: object
          properties:
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
        deposit:
          type: integer
          description: Reservation deposit amount in USD
        design_selections:
          type: array
          description: Initial design option selections
          items:
            type: object
            properties:
              option_id:
                type: string
              quantity:
                type: integer
    Reservation:
      type: object
      properties:
        reservation_id:
          type: string
          description: Unique reservation identifier
        status:
          type: string
          enum:
            - pending
            - confirmed
            - in-contract
            - cancelled
        community_id:
          type: string
        plan_id:
          type: string
        lot_id:
          type: string
        home_id:
          type: string
        base_price:
          type: integer
        deposit_amount:
          type: integer
        estimated_close_date:
          type: string
          format: date
        created_at:
          type: string
          format: date-time
    ReservationList:
      type: object
      properties:
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/Reservation'
        total:
          type: integer
    DesignOption:
      type: object
      properties:
        option_id:
          type: string
          description: Design option identifier
        name:
          type: string
          description: Option name
        category:
          type: string
          description: Option category
        description:
          type: string
        price:
          type: integer
          description: Option price premium
        images:
          type: array
          items:
            type: string
            format: uri
    DesignOptionList:
      type: object
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/DesignOption'
        total:
          type: integer