RentCheck File Requests API

openapi: 3.1.0
info:
  title: RentCheck REST Account Settings File Requests API
  version: 1.0.0
  description: "\n## Mission\nAt RentCheck, our mission is plain and simple: To make renting fair and transparent for everyone involved. \nRentCheck is a property inspection solution that helps property managers save time and resources with easy self-guided inspections that residents can perform from their smartphone. \n\nWith RentCheck, property managers can avoid tenant coordination, eliminate drive time, and standardize their inspection process. \nWe provides real-time visibility to property managers and owners while bringing transparency to the security deposit deduction process.\n\n## API\nThe RentCheck API lets developers tap into the RentCheck ecosystem, building their own RentCheck-powered applications to enable inspection scheduling and creation and to leverage inspection data for a variety of use cases in the property management, maintenance, and insurance spaces.\n\nThe RentCheck REST API supports JSON requests and responses and features a resource-oriented design that generally adheres to the RFC 7321 HTTP/1.1 standard. \nOur API resources provide access to many RentCheck features, including units, buildings, communities, inspections, and residents.\n\n## Credentials\nIn addition to the Bearer Auth, RentCheck will need to send you an application ID and secret. These are required to generate the required application headers (x-app-id & x-app-secret).\nThese values can be obtained from the [RentCheck API integration page](https://app.getrentcheck.com/account/integrations/rentcheck-api).\n\n## Rate Limiting\nThe RentCheck API enforces rate limits to ensure fair usage and prevent abuse. The rate limits are as follows:\n- **Requests per second**: 8\n- **Requests per minute**: 256\n- **Requests per 10 minutes**: 1024\n\nIf you exceed the rate limits, you will receive a 429 Too Many Requests response.\n\n## Pagination\nWhen interacting with endpoints that return a list of items, the results are paginated to help manage large data sets efficiently. The following parameters control pagination:\n- **page_size** (integer): Defines the number of items returned per page. The maximum allowed value is 250. If a value larger than 250 is provided, it will be automatically clamped to 250. This ensures that the system performs optimally and prevents the server from being overwhelmed by too many items in a single response.\n  - **Maximum**: `250`\n- **page_number** (integer): Indicates the page number to retrieve. Pagination starts at `page 0`. If not specified, the first page (`page 0`) is returned by default.\n### Example Request\n```http\nGET /api/v1/inspections?page_size=300&page_number=2\n```\nIn this example, although the `page_size` parameter is set to `300` **for a query with 1500 total results**, the system will return only `250` items per page, as `300` exceeds the maximum allowed value.\n#### Example Response\n```json\n{\n    \"status\": 200,\n    \"data\": [...],\n    \"count\": 250,\n    \"total_results\": 1500\n}\n```\nThis response shows that the `page_size` has been clamped to `250`, despite the initial request for `300`.\n"
  contact:
    name: RentCheck Support
    email: support@getrentcheck.com
servers:
- url: https://prod-public-api.getrentcheck.com
  description: Production server
security:
- bearerAuth: []
  x-app-id: []
  x-app-secret: []
tags:
- name: File Requests
paths:
  /v1/fileRequests:
    post:
      x-internal: true
      summary: Create a file request
      tags:
      - File Requests
      description: Create a file request
      parameters:
      - in: header
        name: x-app-id
        required: false
        schema:
          type: string
        description: 'Optional caller application identifier. When set, the value is persisted as `app_id` on the file request. Not validated further — accepted as any string.

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/file_request_create_request_model'
      responses:
        '201':
          description: Returns the created file request ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 201
                  data:
                    $ref: '#/components/schemas/file_request_response_model'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - document_type is missing
                    - document_type has an invalid value
                    - export_type is missing
                    - export_type has an invalid value
                    - document_id is missing
                    - document_id has an invalid value
                    example: document_id is missing
        '401':
          $ref: '#/components/responses/401'
    get:
      x-internal: true
      summary: Get all file requests
      tags:
      - File Requests
      description: 'Returns the list of file requests created by the authenticated user, optionally filtered by

        status. File requests capture the state of async PDF/ZIP report generation jobs.

        '
      parameters:
      - in: query
        name: filters[status][value]
        schema:
          type: string
          pattern: ^(CREATED|PROCESSING|DONE|ERROR|THROTTLED)(\|(CREATED|PROCESSING|DONE|ERROR|THROTTLED))*$
        description: 'Pipe-separated list of status values to filter by

          (e.g. `CREATED|DONE`). When either

          `filters[status][value]` or `filters[status][condition]` is

          supplied, both are required.

          '
      - in: query
        name: filters[status][condition]
        schema:
          type: string
          enum:
          - any_of
          - none_of
        description: Condition to apply to the status filter. Must be paired with `filters[status][value]` (see above).
      - in: query
        name: page_size
        schema:
          type: integer
          default: 20
        description: The number of elements in the data collection.
      - in: query
        name: last_evaluated_hash_key
        schema:
          type: string
        description: 'Cursor for keyset pagination. Pass the value returned by

          the previous page to fetch the next one.

          '
      - in: query
        name: last_evaluated_range_key
        schema:
          type: integer
          format: int64
        description: 'Range-key cursor (updated_date timestamp in milliseconds)

          for keyset pagination.

          '
      responses:
        '200':
          description: Returns the paginated list of file requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/api_file_request'
                      lastEvaluatedKey:
                        type: object
                        description: 'Cursor for the next page. Both fields are

                          absent when there are no more pages.

                          '
                        properties:
                          last_evaluated_hash_key:
                            type: string
                            description: 'File request id of the last item on this page.

                              Pass back as `last_evaluated_hash_key` to fetch the

                              next page.

                              '
                          last_evaluated_range_key:
                            type: integer
                            format: int64
                            description: '`updated_date` timestamp (ms) of the last item on

                              this page. Pass back as `last_evaluated_range_key`

                              to fetch the next page.

                              '
        '400':
          description: 'The query parameters failed validation. Common causes: an unknown

            `filters[status][condition]` value, a malformed `filters[status][value]`

            string, or an empty status array.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  error:
                    type: string
                    example: '"filters.status.condition" must be one of [any_of, none_of]'
        '401':
          $ref: '#/components/responses/401'
  /v1/fileRequests/{fileRequestId}:
    get:
      x-internal: true
      summary: Get a file request by ID
      tags:
      - File Requests
      description: 'Returns a single file request. Used by the apps to poll for the completion of long-running

        PDF / ZIP report generation jobs and to retrieve the resulting download URL.

        '
      parameters:
      - name: fileRequestId
        in: path
        description: File request ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the raw stored file request document for the requested

            file request. Note: unlike `GET /v1/fileRequests` (which returns a

            projected shape), this endpoint returns the underlying entity

            unchanged — dates are epoch-millisecond numbers and additional

            persisted fields (`user_id`, `org_id`, `file_name`, `dont_notify`,

            `filters`, `params`) are echoed back.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/file_request_v1_get_by_id_response_model'
        '400':
          description: 'Bad request — the requested file request does not exist or is not

            owned by the authenticated user. The handler intentionally surfaces

            this case as 400 (not 404) to avoid leaking the existence of

            another user''s file request.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - id has an invalid value
                    example: id has an invalid value
        '401':
          $ref: '#/components/responses/401'
components:
  schemas:
    file_request_v1_get_by_id_response_model:
      x-internal: true
      type: object
      required:
      - id
      - document_id
      - document_type
      - export_type
      - user_id
      - org_id
      - status
      - created_date
      - updated_date
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        document_id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        document_type:
          type: string
          description: Name of the report to be generated.
          enum:
          - INSPECTION_REPORT
          - MAINTENANCE_REPORT
          - WORK_ORDER
          - INSPECTION_IMAGES
          - BUILDINGS_LIST_EXPORT
          - COMMUNITIES_LIST_EXPORT
          - INSPECTION_LIST_EXPORT
          - MAINTENANCE_REPORTS_LIST_EXPORT
          - MAINTENANCE_FLAGS_LIST_EXPORT
          - UNITS_LIST_EXPORT
          - SUBSCRIPTION_REPORT_LIST_EXPORT
          example: INSPECTION_REPORT
        export_type:
          type: string
          description: Format of the exported report.
          enum:
          - PDF
          - ZIP
          - CSV
          example: PDF
        user_id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        org_id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        status:
          type: string
          description: Current status of the file request.
          enum:
          - CREATED
          - PROCESSING
          - DONE
          - ERROR
          - THROTTLED
          example: DONE
        error_message:
          type: string
          description: Error message describing why the file request failed, when status is `ERROR`.
        created_date:
          type: integer
          format: int64
          description: Epoch-millisecond timestamp at which the file request was created. The getById endpoint returns the raw stored document so this is a `number`, not the ISO string returned by `GET /v1/fileRequests`.
        updated_date:
          type: integer
          format: int64
          description: Epoch-millisecond timestamp of the most recent update. Same caveat as `created_date`.
        file_name:
          type: string
          description: Server-side filename for the generated artifact, used to derive the download URL.
        file_location:
          type: string
          format: uri
          description: URL where the generated document can be downloaded once the request completes. Only present once `file_name` is set.
        dont_notify:
          type: boolean
          description: When `true`, the system will not notify the requesting user when the artifact is ready.
        filters:
          type: object
          additionalProperties: true
          description: Per-document-type filter payload that was used to produce the artifact (shape varies by `document_type`).
        params:
          type: object
          description: Additional parameters captured at request time (e.g. share recipients for an inspection PDF).
          properties:
            send_to:
              type: array
              items:
                type: string
                format: email
            note:
              type: string
    api_file_request:
      type: object
      required:
      - id
      - document_id
      - document_type
      - export_type
      - status
      - created_date
      - updated_date
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        document_id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        document_type:
          type: string
          description: Name of the report to be generated.
          enum:
          - INSPECTION_REPORT
          - MAINTENANCE_REPORT
          - WORK_ORDER
          - INSPECTION_IMAGES
          - BUILDINGS_LIST_EXPORT
          - COMMUNITIES_LIST_EXPORT
          - INSPECTION_LIST_EXPORT
          - MAINTENANCE_REPORTS_LIST_EXPORT
          - MAINTENANCE_FLAGS_LIST_EXPORT
          - UNITS_LIST_EXPORT
          - SUBSCRIPTION_REPORT_LIST_EXPORT
          example: INSPECTION_REPORT
        export_type:
          type: string
          description: Format of the exported report.
          enum:
          - PDF
          - ZIP
          - CSV
          example: PDF
        status:
          type: string
          description: Current status of the file request.
          enum:
          - CREATED
          - PROCESSING
          - DONE
          - ERROR
          - THROTTLED
          example: DONE
        error_message:
          type: string
          description: Error message describing why the file request failed, when status is `ERROR`.
        file_location:
          type: string
          format: uri
          description: URL where the generated document can be downloaded once the request completes. Only present once the request has produced a file (i.e. the underlying `file_name` is set server-side).
        created_date:
          type: string
          format: date-time
          description: ISO-8601 timestamp at which the file request was created.
        updated_date:
          type: string
          format: date-time
          description: ISO-8601 timestamp of the most recent update to the file request.
    file_request_response_model:
      x-internal: true
      type: object
      required:
      - fileRequestId
      properties:
        fileRequestId:
          type: string
          description: Entity ID
          example: fbb2fcf6-4bf5-48b5-9283-4d284a11d317
    file_request_create_request_model:
      x-internal: true
      description: 'A file request is the API surface for asynchronous PDF/ZIP/CSV report generation. The required fields depend on `document_type`: for per-record exports (`INSPECTION_REPORT`, `MAINTENANCE_REPORT`, `WORK_ORDER`, `INSPECTION_IMAGES`) `document_id` is required; for list exports (`*_LIST_EXPORT`) `document_id` is omitted and the server generates one for the resulting file.'
      oneOf:
      - type: object
        required:
        - document_type
        - export_type
        - document_id
        properties:
          document_type:
            type: string
            description: Name of the report to be generated.
            enum:
            - INSPECTION_REPORT
            - MAINTENANCE_REPORT
            - WORK_ORDER
            - INSPECTION_IMAGES
            example: INSPECTION_REPORT
          export_type:
            type: string
            description: Format of the exported report.
            enum:
            - PDF
            - ZIP
            - CSV
            example: PDF
          document_id:
            type: string
            description: ID of the document you are trying to export
            example: fbb2fcf6-4bf5-48b5-9283-4d284a11d317
          dont_notify:
            type: boolean
            description: Specify whether to email the requestor a copy of the file
            example: true
          throttled:
            type: boolean
            description: When true, the request is debounced against any other pending throttled request for the same `document_id` — the prior pending request is deleted before the new one is enqueued.
          filters:
            type: object
            description: Optional per-record export delivery filters. When `send_to` is provided the resulting file is emailed to those recipients in addition to the requesting user; `note` is included in the email body.
            properties:
              send_to:
                type: array
                items:
                  type: string
                  format: email
                description: Email addresses to send the resulting file to once generation completes.
              note:
                type: string
                description: Free-form note appended to the recipient email.
      - type: object
        required:
        - document_type
        - export_type
        properties:
          document_type:
            type: string
            description: Name of the report to be generated.
            enum:
            - BUILDINGS_LIST_EXPORT
            - COMMUNITIES_LIST_EXPORT
            - INSPECTION_LIST_EXPORT
            - MAINTENANCE_REPORTS_LIST_EXPORT
            - MAINTENANCE_FLAGS_LIST_EXPORT
            - UNITS_LIST_EXPORT
            - SUBSCRIPTION_REPORT_LIST_EXPORT
            example: INSPECTION_REPORT
          export_type:
            type: string
            description: Format of the exported report.
            enum:
            - PDF
            - ZIP
            - CSV
            example: PDF
          dont_notify:
            type: boolean
            description: Specify whether to email the requestor a copy of the file
            example: true
          throttled:
            type: boolean
            description: When true, the request is debounced against any other pending throttled request — the prior pending request is deleted before the new one is enqueued.
          filters:
            type: object
            description: Optional list-export filter criteria. Shape varies by `document_type` — for `INSPECTION_LIST_EXPORT` it matches the inspection-list filter shape (`search`, `archived`, `assigned_to`, `inspection_template`, `inspection_status`, `team`, `property`, `due_date`, `completed_date`, etc.); for `*_LIST_EXPORT` variants it matches the matching list endpoint filter shape.
            additionalProperties: true
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                description: HTTP status code
                example: 401
              error:
                type: string
                description: Error message
                enum:
                - token is not valid
                - authorization header is empty
                - authorization header is not valid
                - 'format for Authorization must be: Bearer [token]'
                - refresh token is not valid for resources
                - not well-formed token
                example: token is not valid
  securitySchemes:
    bearerAuth:
      description: Authorization key needed to use the API
      type: http
      scheme: bearer
      bearerFormat: JWT
    x-app-id:
      description: Represents the identification of you application
      type: apiKey
      name: x-app-id
      in: header
      required: true
    x-app-secret:
      description: Represents the secret for your application
      type: apiKey
      name: x-app-secret
      in: header
      required: true