> ## 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 Research Report

> Create an active research report 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 Research Report API for your account. The token's user also needs a research report seat on the account.</Warning>

- Without `name`, the report is named after the property with " Report" added, for example "Marina Landing Report". A counter is added 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.
- You can create more than one research report for the same property. `reactivated` is always `false`.
- `unit_count_override` is saved for the property in your account, so it also applies outside this report.
- The seat is checked after the request itself is validated, so a request with other problems returns 400, 404 or 422 first.



## OpenAPI

````yaml /openapi/v2/schema.json post /research_reports
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:
  /research_reports:
    post:
      tags:
        - Market Surveys
      summary: Create Research Report
      description: >-
        Create an active research report 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 Research Report API for your account. The token's user also needs a
        research report seat on the account.</Warning>


        - Without `name`, the report is named after the property with " Report"
        added, for example "Marina Landing Report". A counter is added 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.

        - You can create more than one research report for the same property.
        `reactivated` is always `false`.

        - `unit_count_override` is saved for the property in your account, so it
        also applies outside this report.

        - The seat is checked after the request itself is validated, so a
        request with other problems returns 400, 404 or 422 first.
      operationId: createV2ResearchReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompSetCreateRequest'
            example:
              account_id: '{account_id}'
              iq_property_id: 781245
              unit_count_override: 290
      responses:
        '201':
          description: The research report was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompSetCreateResponse'
              example:
                id: 52311
                name: Marina Landing Report
                category: research_report
                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/research-reports/52311/market-survey
                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: unit_count_override is invalid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Forbidden. Returns an empty body when `account_id` is missing, the
            user lacks access to the account, or the account does not have the
            Research Report API feature. Returns an error body when the token's
            user has no research report seat on the account. 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'
              examples:
                no_research_report_seat:
                  summary: The token's user has no research report seat
                  value:
                    error: >-
                      You need a research report seat on this account to create
                      research reports.
        '404':
          $ref: '#/components/responses/PropertyNotFound'
        '409':
          $ref: '#/components/responses/CreateConflict'
        '422':
          description: The research report could not be created.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/InvalidPropertyIdsError'
              examples:
                invalid_comps:
                  value:
                    error: Invalid comp_property_ids
                    invalid_property_ids:
                      - 990001
                name_taken:
                  value:
                    error: Name has already been taken
        '429':
          $ref: '#/components/responses/RateLimitOrQuotaExceeded'
        '500':
          description: The research report could not be saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Research report could not be created
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
    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
    CreateConflict:
      description: This request conflicted with another one in progress. Retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: This conflicted with another request in progress. Retry shortly.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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