> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apartmentiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Properties

> Search properties by text query, optionally scoped by stakeholder entities.

<Warning>Requires Explore Pro access.</Warning>



## OpenAPI

````yaml /openapi/v2/schema.json post /properties/search
openapi: 3.1.0
info:
  title: ApartmentIQ API V2
  version: 2.0.0
  termsOfService: https://www.getapartmentiq.com/terms
  x-logo:
    url: https://developers.apartmentiq.io/logo.svg
    altText: ApartmentIQ
  description: >-
    ApartmentIQ API V2 endpoints for account discovery, search, and bulk Explore
    data.
servers:
  - url: https://data.apartmentiq.io/apartmentiq/api/v2
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Account discovery endpoints.
  - name: Amenities
    description: Amenity discovery endpoints.
  - name: Properties
    description: Property search endpoints.
  - name: Markets
    description: Market and geo-boundary search endpoints.
  - name: Organizations
    description: Organization search endpoints.
  - name: Bulk
    description: Bulk property, market, quota, and forecast exports.
paths:
  /properties/search:
    post:
      tags:
        - Properties
      summary: Search Properties
      description: >-
        Search properties by text query, optionally scoped by stakeholder
        entities.


        <Warning>Requires Explore Pro access.</Warning>
      operationId: searchV2Properties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PropertySearchRequest'
            example:
              account_id: '{account_id}'
              query: Marina
              page: 1
              per_page: 50
              stakeholder_entity_ids:
                - 11
                - 22
      responses:
        '200':
          description: Property search results and pagination metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertySearchResponse'
              example:
                properties:
                  - id: 781245
                    property_name: Marina Landing
                    city: Austin
                    state: TX
                    zip_code: '78701'
                    unit_count: 284
                    year_built: 2019
                    year_renovated: null
                    property_class: A
                    address: 401 Riverfront Dr
                    image_url: https://cdn.example.com/properties/marina-landing.jpg
                    latitude: 30.2647
                    longitude: -97.7478
                  - id: 781266
                    property_name: Marina Heights
                    city: Austin
                    state: TX
                    zip_code: '78703'
                    unit_count: 196
                    year_built: 2012
                    year_renovated: 2021
                    property_class: B
                    address: 88 Lakeview Ave
                    image_url: null
                    latitude: 30.2799
                    longitude: -97.7696
                pagination:
                  current_page: 1
                  total_pages: 2
                  total_count: 76
                  per_page: 50
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ExploreAccessForbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PropertySearchRequest:
      type: object
      properties:
        account_id:
          $ref: '#/components/schemas/AccountId'
        query:
          type: string
          description: Search term.
        page:
          type: integer
          minimum: 1
          default: 1
          description: One-based page number. Values less than 1 are treated as 1.
        per_page:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
          description: Rows per page. Values above 100 are capped at 100.
        stakeholder_entity_ids:
          anyOf:
            - type: array
              items:
                anyOf:
                  - type: integer
                  - type: string
            - type: string
          description: >-
            Optional stakeholder entity IDs. Rails accepts arrays or
            comma-delimited strings.
      required:
        - account_id
        - query
      additionalProperties: false
    PropertySearchResponse:
      type: object
      properties:
        properties:
          type: array
          items:
            $ref: '#/components/schemas/PropertySearchProperty'
          description: Properties matching the search query and filters.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination details for the property search results.
      required:
        - properties
        - pagination
      additionalProperties: false
      description: Paginated property search results.
    AccountId:
      anyOf:
        - type: integer
        - type: string
      description: ApartmentIQ account ID used to set the request account context.
    PropertySearchProperty:
      type: object
      properties:
        id:
          type: integer
          description: ApartmentIQ property ID.
        property_name:
          type:
            - string
            - 'null'
          description: Property display name.
        city:
          type:
            - string
            - 'null'
          description: Property city.
        state:
          type:
            - string
            - 'null'
          description: Property state abbreviation.
        zip_code:
          type:
            - string
            - 'null'
          description: Property postal code.
        unit_count:
          type:
            - integer
            - 'null'
          description: Known unit count for the property.
        year_built:
          type:
            - integer
            - 'null'
          description: Year the property was built, when known.
        year_renovated:
          type:
            - integer
            - 'null'
          description: Year the property was renovated, when known.
        property_class:
          type:
            - string
            - 'null'
          description: Property class, when classified.
        address:
          type:
            - string
            - 'null'
          description: Property street address.
        image_url:
          type:
            - string
            - 'null'
          description: Image URL for the property, when available.
        latitude:
          type:
            - number
            - 'null'
          description: Property latitude.
        longitude:
          type:
            - number
            - 'null'
          description: Property longitude.
      required:
        - id
        - property_name
        - city
        - state
        - zip_code
        - unit_count
        - year_built
        - year_renovated
        - property_class
        - address
        - image_url
        - latitude
        - longitude
      additionalProperties: false
      description: Property returned by the property search endpoint.
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          description: Current page number in the result set.
        total_pages:
          type: integer
          description: Total number of pages available for the request.
        total_count:
          type: integer
          description: Total number of matching records across all pages.
        per_page:
          type: integer
          description: Maximum number of records returned per page.
      required:
        - current_page
        - total_pages
        - total_count
        - per_page
      additionalProperties: false
      description: Pagination details for list-style responses.
    Error:
      type: object
      description: Error response payload.
      properties:
        error:
          type: string
          description: Short error message.
        message:
          type: string
          description: Additional error details, when available.
        quota_limit:
          type: integer
          description: Quota limit that applied to the request, when relevant.
        quota_usage:
          type: integer
          description: Quota already used, when relevant.
      required:
        - error
      additionalProperties: true
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ExploreAccessForbidden:
      description: Forbidden - The user lacks account access or Explore Pro access.
    RateLimitExceeded:
      description: >-
        Rate limit exceeded. Inspect the rate limit headers and wait before
        retrying.
      headers:
        X-RateLimit-Limit:
          description: The limit that applied to the request.
          schema:
            type: string
        X-RateLimit-Reset-After:
          description: The rate limit window length, in seconds.
          schema:
            type: string
        X-RateLimit-Reset:
          description: Unix timestamp when the current window resets.
          schema:
            type: string
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: string
      content:
        text/plain:
          schema:
            type: string
          example: |
            You have exceeded the rate limit for this API.
    InternalServerError:
      description: An unexpected error occurred while processing the request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````