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

# Create Market Survey

> Create an active market survey with a property as its subject.

<Warning>Available upon request. This endpoint is not enabled for all customers. Please reach out to your account representative to turn on the Market Survey API for your account. Each new or reactivated market survey counts as a market survey addition, exactly like adding one in ApartmentIQ.</Warning>

- Without `name`, the survey is named after the property, with a counter if that name is taken.
- The floorplan range comes from the bedroom counts the property has advertised, or 0 to 5 (studio to 5 bedrooms) when it has none.
- Without `comp_property_ids`, comps are selected automatically, up to `target_comp_count` minus the subject (9 by default). With `comp_property_ids`, every ID you send is added, even past that target.
- If the account has a deactivated market survey for this property, it is reactivated and `reactivated` is `true`. It keeps its floorplan range, target comp count and comps, and is topped up to its target comp count. With `name`, it is renamed. If that name is taken, the response is 422 and the survey stays deactivated. Without `name`, it keeps its old name. `comp_property_ids` is ignored, but still validated.
- `unit_count_override` is the unit count billed for the survey. It is saved for the property in your account, so it also applies outside this survey.
- The confirmation email goes to the API token's user.
- A 422 for an existing survey includes its `comp_set_id`, so a client that lost a response can find the survey it created.



## OpenAPI

````yaml /openapi/v2/schema.json post /market_surveys
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:
  /market_surveys:
    post:
      tags:
        - Market Surveys
      summary: Create Market Survey
      description: >-
        Create an active market survey with a property as its subject.


        <Warning>Available upon request. This endpoint is not enabled for all
        customers. Please reach out to your account representative to turn on
        the Market Survey API for your account. Each new or reactivated market
        survey counts as a market survey addition, exactly like adding one in
        ApartmentIQ.</Warning>


        - Without `name`, the survey is named after the property, with a counter
        if that name is taken.

        - The floorplan range comes from the bedroom counts the property has
        advertised, or 0 to 5 (studio to 5 bedrooms) when it has none.

        - Without `comp_property_ids`, comps are selected automatically, up to
        `target_comp_count` minus the subject (9 by default). With
        `comp_property_ids`, every ID you send is added, even past that target.

        - If the account has a deactivated market survey for this property, it
        is reactivated and `reactivated` is `true`. It keeps its floorplan
        range, target comp count and comps, and is topped up to its target comp
        count. With `name`, it is renamed. If that name is taken, the response
        is 422 and the survey stays deactivated. Without `name`, it keeps its
        old name. `comp_property_ids` is ignored, but still validated.

        - `unit_count_override` is the unit count billed for the survey. It is
        saved for the property in your account, so it also applies outside this
        survey.

        - The confirmation email goes to the API token's user.

        - A 422 for an existing survey includes its `comp_set_id`, so a client
        that lost a response can find the survey it created.
      operationId: createV2MarketSurvey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompSetCreateRequest'
            example:
              account_id: '{account_id}'
              iq_property_id: 781245
              comp_property_ids:
                - 781266
                - 781301
      responses:
        '201':
          description: The market survey was created or reactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompSetCreateResponse'
              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: 781301
                    property_name: Riverside Commons
                    score: 0.74
                app_url: https://app.apartmentiq.io/accounts/1042/market-surveys/52310
                reactivated: false
        '400':
          description: A parameter is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_property:
                  value:
                    error: iq_property_id is required
                invalid_param:
                  value:
                    error: comp_property_ids is invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Forbidden - account_id is missing, the user lacks access to the
            requested account, or the account does not have the Market Survey
            API feature. A token that is not allowed to call the API, such as an
            MCP token, also gets 403 with an empty body.
        '404':
          $ref: '#/components/responses/PropertyNotFound'
        '409':
          description: >-
            Another create for this property, or another conflicting request, is
            in progress. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                same_property:
                  value:
                    error: >-
                      A market survey for this property is already being
                      created. Retry shortly.
                conflict:
                  value:
                    error: >-
                      This conflicted with another request in progress. Retry
                      shortly.
        '422':
          description: The market survey could not be created.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/InvalidPropertyIdsError'
                  - $ref: '#/components/schemas/DuplicateMarketSurveyError'
              examples:
                existing_survey:
                  value:
                    error: A market survey already exists for this property.
                    comp_set_id: 52310
                invalid_comps:
                  value:
                    error: Invalid comp_property_ids
                    invalid_property_ids:
                      - 990001
                name_taken:
                  value:
                    error: Name has already been taken
                salesforce:
                  value:
                    error: >-
                      We were unable to record this market survey in Salesforce.
                      Please contact support.
        '429':
          $ref: '#/components/responses/RateLimitOrQuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CompSetCreateRequest:
      type: object
      description: >-
        Request contract for creating a market survey or research report.
        Integer fields also accept integer strings such as "300".
      properties:
        account_id:
          $ref: '#/components/schemas/AccountId'
        iq_property_id:
          type: integer
          description: ApartmentIQ property ID of the subject property.
        name:
          type: string
          minLength: 1
          maxLength: 150
          description: >-
            Name for the comp set. Leading and trailing spaces are removed. Must
            be unique in the account.
        unit_count_override:
          type: integer
          minimum: 1
          maximum: 100000
          description: >-
            Unit count to use for the subject property when it differs from
            ApartmentIQ's count. It is saved for the property in the account, so
            it also applies outside this comp set. On a market survey, it is the
            unit count billed.
        comp_property_ids:
          type: array
          items:
            type: integer
          description: >-
            Exact comps to use, skipping automatic comp selection. Must hold 1
            to 50 IDs after the subject property and duplicates are removed.
      required:
        - account_id
        - iq_property_id
    CompSetCreateResponse:
      allOf:
        - $ref: '#/components/schemas/CompSet'
        - type: object
          properties:
            reactivated:
              type: boolean
              description: >-
                True when an existing deactivated market survey was reactivated
                instead of created. Always false for research reports.
          required:
            - reactivated
    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
    DuplicateMarketSurveyError:
      type: object
      description: The account already has an active market survey for this property.
      properties:
        error:
          type: string
        comp_set_id:
          type: integer
          description: ID of the existing active market survey.
      required:
        - error
        - comp_set_id
    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'
    PropertyNotFound:
      description: Property not found, or not a property the API exposes to this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Property 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.