RentCheck Residents V3 API

openapi: 3.1.0
info:
  title: RentCheck REST Account Settings Residents V3 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: Residents V3
paths:
  /v3/residents:
    get:
      x-internal: true
      summary: Get all residents (v3)
      tags:
      - Residents V3
      description: 'Returns a paginated list of resident digests. V3 returns a trimmed `resident_v3_response_model`

        projection (basic identity + `primary_occupancy`) and uses the `filters[...]` / `options[...]`

        nested query-param syntax. Used internally by the web and mobile apps.

        '
      parameters:
      - in: query
        name: filters[search]
        description: Search value among tenant emails, first and last name, current and future lease property address.
        schema:
          type: string
      - in: query
        name: filters[active]
        description: When `true`, returns residents with a current and/or a future lease. When `false`, returns residents with a past lease or no lease information. HTTP query strings are always strings, so the value is compared against the literal `'true'` / `'false'`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - in: query
        name: filters[deleted]
        description: 'When the literal string `''true''`, deleted residents are included. Any

          other value (including `''false''`, missing, or anything else) is

          treated as `false`. There is no explicit enum validation, so unknown

          values are silently normalised to `false` rather than rejected as 400.

          '
        schema:
          type: string
          example: 'false'
          default: 'false'
      - in: query
        name: filters[emails]
        description: Email(s) to filter residents by. Multiple values should be comma-separated.
        schema:
          type: string
      - in: query
        name: filters[property_id]
        description: Filters all residents for a specific property.
        schema:
          type: string
      - in: query
        name: filters[occupancy_status][value]
        description: Occupancy status(es) to filter residents by. Multiple values should be concatenated with a `|`. Allowed individual values are `future`, `past`, and `current`.
        schema:
          type: string
          pattern: ^(future|past|current)(\|(future|past|current))*$
      - in: query
        name: filters[occupancy_status][condition]
        description: Condition to apply to the occupancy_status filter. The validator only accepts `any_of`. Note also that `filters[active]` and `filters[occupancy_status]` are mutually exclusive — supplying both is rejected by the request validator.
        schema:
          type: string
          enum:
          - any_of
      - in: query
        name: occupancy_status[]
        deprecated: true
        schema:
          type: array
          items:
            type: string
        description: 'Legacy multi-value occupancy status filter, still accepted. Prefer

          `filters[occupancy_status][value]`.

          '
      - in: query
        name: options[pagination][page_size]
        description: How many items to be returned for each page.
        schema:
          type: integer
          default: 20
      - in: query
        name: options[pagination][page_number]
        description: Zero-indexed page number.
        schema:
          type: integer
          default: 0
      - in: query
        name: options[sort][sort_type]
        description: 'Sort list in ascending or descending order. Accepted

          case-insensitively.

          '
        schema:
          type: string
          default: ASC
          enum:
          - ASC
          - DESC
          - asc
          - desc
      - in: query
        name: options[sort][sort_by]
        description: Sort list by a specific property.
        schema:
          type: string
          default: first_name
          enum:
          - first_name
          - last_name
          - emails
          - property_address
          - lease_start
          - lease_end
          - status
      responses:
        '200':
          description: Returns all residents
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/resident_v3_response_model'
                  count:
                    type: integer
                    description: Amount of elements in `data`.
                  total_results:
                    type: integer
                    description: Amount of total elements according to search criteria.
        '400':
          description: 'The query parameters failed validation. Common causes: `filters[active]` and

            `filters[occupancy_status]` supplied together (rejected as mutually exclusive), an

            `options[sort][sort_by]` value outside the enum, or a malformed

            `filters[occupancy_status][value]` string.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  error:
                    type: string
                    example: '"options.sort.sort_by" must be one of [first_name, last_name, emails, property_address, lease_start, lease_end, status]'
        '401':
          $ref: '#/components/responses/401'
components:
  schemas:
    resident_v3_response_model:
      type: object
      required:
      - id
      - first_name
      - last_name
      - phone_numbers
      - emails
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        first_name:
          type: string
          description: The Resident's first name.
          example: Resident Name
        last_name:
          type: string
          description: The Resident's last name.
          example: Resident Lastname
        phone_numbers:
          type: array
          items:
            type: string
          description: Resident's phone numbers
          example:
          - '+17035556390'
        emails:
          type: array
          description: Resident's emails
          items:
            type: string
          example:
          - resident@email.com
        sync_data:
          oneOf:
          - title: RentManager Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              vendor:
                type: string
                enum:
                - rentmanager
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              x_id:
                type: string
              location_id:
                type: string
              integration_id:
                type: string
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
          - title: Yardi Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              vendor:
                type: string
                enum:
                - yardi
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              code:
                type: string
              parent_code:
                type: string
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
          - title: AppFolio Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              vendor:
                type: string
                enum:
                - appfolio
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              short_property_id:
                type: string
              short_unit_id:
                type: string
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
              upload_response:
                type: array
                items:
                  type: object
                  required:
                  - resource
                  - resource_id
                  - uploaded_id
                  properties:
                    resource:
                      type: string
                      enum:
                      - units
                      - properties
                      - occupancies
                    resource_id:
                      type: string
                    uploaded_id:
                      type: string
          - title: Buildium Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              vendor:
                type: string
                enum:
                - buildium
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
          - title: Jenark Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              vendor:
                type: string
                enum:
                - jenark
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
          - title: Rentvine Sync
            type: object
            required:
            - vendor
            - last_sync
            properties:
              vendor:
                type: string
                enum:
                - rentvine
              last_sync:
                type: string
                description: The last time the resident was synced with external sources.
                example: 2024-12-02 14:15:37.925000
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              x_id:
                type: string
              status:
                type: string
                description: Latest manual-sync lifecycle state, when the integration exposes it.
                enum:
                - scheduled
                - processing
                - success
                - error
              error:
                type: string
                nullable: true
        primary_occupancy:
          type: object
          required:
          - id
          - status
          - lease_end
          - lease_start
          description: Present when the tenant has a primary occupancy. `lease_start` / `lease_end` are always emitted keys but are `null` when the value is empty, so the property is required but nullable.
          properties:
            id:
              type: string
              description: Entity ID
              example: 00BRcZPSakXz6w7RYoE
            status:
              type: string
              description: Indicates if the tenant is a future, past or current one
              enum:
              - future
              - past
              - current
            lease_start:
              type: string
              description: The date the Resident's current lease starts.
              example: 2021-01-15 00:00:00
              nullable: true
            lease_end:
              type: string
              description: The date the Resident's current lease should end.
              example: 2022-01-15 00:00:00
              nullable: true
            property:
              type: object
              required:
              - id
              - address
              description: This is the entity id of the Unit, Building, or Community that the entity is for. Optional — legacy occupancies can lack property data.
              properties:
                id:
                  type: string
                  description: Selected entity's property id
                  example: 00BRcZPSakXz6w7RYoE
                address:
                  type: string
                  description: Selected entity's property address
                  example: 2001 Red Gates
  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