> ## 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.

# Replace Comps

> Set a comp set's comps to exactly the list you send. Comps missing from the list are removed, and new ones are added. Sending the same list again changes nothing, so you can sync from your own system safely.

- Owned properties in the comp set, such as the subject, are never removed. Send only competitive comps.
- Comps already in the comp set are kept whatever their status, so you can send back the list you received.
- New comps must be properties ApartmentIQ can use as comps. Otherwise nothing changes and the response lists the invalid IDs.
- The list can hold more comps than `target_comp_count`.
- Later automatic top-ups can add comps up to `target_comp_count`: reactivating a market survey, and the daily refresh for comp sets that update automatically. Comp sets created through the API do not update automatically.
- Every change is recorded in the comp set's history under the API token's user.
- If you get a 500, the change may already be saved. Send the same list again.



## OpenAPI

````yaml /openapi/v2/schema.json put /comp_sets/{comp_set_id}/comps
openapi: 3.1.0
info:
  title: ApartmentIQ API V2
  version: 2.7.2
  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, organization
    details, bulk Explore data, dataset downloads, and market survey and
    research report creation.
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: Datasets
    description: Complete dataset snapshot downloads.
  - name: Bulk
    description: Bulk property, market, organization, quota, and forecast exports.
  - name: Market Surveys
    description: >-
      Comp suggestions, market survey and research report creation, and comp set
      edits.
paths:
  /comp_sets/{comp_set_id}/comps:
    put:
      tags:
        - Market Surveys
      summary: Replace Comps
      description: >-
        Set a comp set's comps to exactly the list you send. Comps missing from
        the list are removed, and new ones are added. Sending the same list
        again changes nothing, so you can sync from your own system safely.


        - Owned properties in the comp set, such as the subject, are never
        removed. Send only competitive comps.

        - Comps already in the comp set are kept whatever their status, so you
        can send back the list you received.

        - New comps must be properties ApartmentIQ can use as comps. Otherwise
        nothing changes and the response lists the invalid IDs.

        - The list can hold more comps than `target_comp_count`.

        - Later automatic top-ups can add comps up to `target_comp_count`:
        reactivating a market survey, and the daily refresh for comp sets that
        update automatically. Comp sets created through the API do not update
        automatically.

        - Every change is recorded in the comp set's history under the API
        token's user.

        - If you get a 500, the change may already be saved. Send the same list
        again.
      operationId: replaceV2CompSetComps
      parameters:
        - name: comp_set_id
          in: path
          required: true
          schema:
            type: integer
          description: Comp set ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompSetCompsReplaceRequest'
            example:
              account_id: '{account_id}'
              property_ids:
                - 781266
                - 781390
      responses:
        '200':
          description: The comps were applied. Both lists are empty when nothing changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompSetCompsReplaceResponse'
              example:
                id: 52310
                name: Marina Landing
                category: market_survey
                account_id: 1042
                active: true
                min_floorplan: 0
                max_floorplan: 3
                target_comp_count: 10
                subject_property:
                  id: 781245
                  custom: false
                  property_name: Marina Landing
                  address: 401 Riverfront Dr, Austin, TX 78701
                comps:
                  - property_id: 781266
                    property_name: Marina Heights
                    score: 0.82
                  - property_id: 781390
                    property_name: The Foundry
                    score: 0.77
                app_url: https://app.apartmentiq.io/accounts/1042/market-surveys/52310
                added_property_ids:
                  - 781390
                removed_property_ids:
                  - 781301
        '400':
          description: >-
            property_ids is missing, is not an array of integers or integer
            strings, or has more than 50 distinct IDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: property_ids is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Forbidden - account_id is missing, the user lacks access to the
            requested account, or the user can't edit this comp set. Only the
            last case has a response body. A token that is not allowed to call
            the API, such as an MCP token, also gets 403 with an empty body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: You do not have permission to edit this comp set
        '404':
          $ref: '#/components/responses/CompSetNotFound'
        '422':
          description: >-
            Some new comps are not properties ApartmentIQ can use as comps.
            Nothing changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidPropertyIdsError'
              example:
                error: Invalid property_ids
                invalid_property_ids:
                  - 990001
        '429':
          $ref: '#/components/responses/RateLimitOrQuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CompSetCompsReplaceRequest:
      type: object
      description: Request contract for replacing a comp set's comps.
      properties:
        account_id:
          $ref: '#/components/schemas/AccountId'
        property_ids:
          type: array
          items:
            type: integer
          description: >-
            The complete list of comps you want, up to 50 distinct IDs. Integer
            strings such as "781266" are accepted. Duplicates are collapsed. An
            empty list removes every comp. Owned properties are ignored.
      required:
        - account_id
        - property_ids
    CompSetCompsReplaceResponse:
      allOf:
        - $ref: '#/components/schemas/CompSet'
        - type: object
          properties:
            added_property_ids:
              type: array
              items:
                type: integer
              description: Comps added by this request, ascending.
            removed_property_ids:
              type: array
              items:
                type: integer
              description: Comps removed by this request, ascending.
          required:
            - added_property_ids
            - removed_property_ids
    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
    InvalidPropertyIdsError:
      type: object
      description: Some property IDs are not properties ApartmentIQ can use as comps.
      properties:
        error:
          type: string
        invalid_property_ids:
          type: array
          items:
            type: integer
      required:
        - error
        - invalid_property_ids
    AccountId:
      anyOf:
        - type: integer
        - type: string
      description: ApartmentIQ account ID used to set the request account context.
    CompSet:
      type: object
      description: A market survey or research report.
      properties:
        id:
          type: integer
          description: Comp set ID.
        name:
          type: string
        category:
          type: string
          enum:
            - market_survey
            - research_report
        account_id:
          type: integer
          description: ApartmentIQ account ID the comp set belongs to.
        active:
          type: boolean
        min_floorplan:
          type: integer
          minimum: 0
          maximum: 5
          description: Lowest bedroom count included (0 is studio).
        max_floorplan:
          type: integer
          minimum: 0
          maximum: 5
          description: Highest bedroom count included.
        target_comp_count:
          type: integer
          description: >-
            The number of properties automatic comp selection fills the comp set
            to, counting the subject property. 10 means automatic selection adds
            up to 9 comps. A custom subject is not counted. It is not a limit:
            comps you add yourself can go past it.
          minimum: 0
        subject_property:
          anyOf:
            - $ref: '#/components/schemas/CompSetSubjectProperty'
            - type: 'null'
          description: >-
            The comp set's subject property. When a comp set has more than one
            owned property, this is the one with the lowest ID.
        comps:
          type: array
          description: >-
            Comps sorted by score, highest first. Comps without a score come
            last.
          items:
            $ref: '#/components/schemas/CompSetComp'
        app_url:
          type: string
          format: uri
          description: Link to the comp set in ApartmentIQ.
      required:
        - id
        - name
        - category
        - account_id
        - active
        - min_floorplan
        - max_floorplan
        - target_comp_count
        - subject_property
        - comps
        - app_url
    CompSetSubjectProperty:
      type: object
      description: The comp set's subject property.
      properties:
        id:
          type:
            - integer
            - 'null'
          description: ApartmentIQ property ID. Null for a custom subject property.
        custom:
          type: boolean
          description: >-
            True when the subject is a custom (hypothetical) property rather
            than an ApartmentIQ property.
        property_name:
          type:
            - string
            - 'null'
        address:
          type:
            - string
            - 'null'
      required:
        - id
        - custom
        - property_name
        - address
    CompSetComp:
      type: object
      description: A comp in a comp set.
      properties:
        property_id:
          type: integer
          description: ApartmentIQ property ID.
        property_name:
          type:
            - string
            - 'null'
        score:
          type:
            - number
            - 'null'
          description: >-
            Comp score against the subject property, from 0 to 1. 0 when the
            comp could not be scored, for example when the comp set has no
            subject property. Null when the scorer returned no score for this
            comp.
      required:
        - property_id
        - property_name
        - score
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CompSetNotFound:
      description: No comp set with this ID in the requested account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Comp set not found
    RateLimitOrQuotaExceeded:
      description: >-
        A general API rate limit or account trial API quota was exceeded. For a
        trial quota response, quota_usage is the number of requests already
        counted and quota_limit is the account limit.
      headers:
        Retry-After:
          description: >-
            Seconds to wait before retrying when supplied by the active rate
            limiter.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Trial API quota limit exceeded
            quota_limit: 1000
            quota_usage: 1000
        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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.