RentCheck Residents (deprecated) API

openapi: 3.1.0
info:
  title: RentCheck REST Account Settings Residents (deprecated) 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 (deprecated)
paths:
  /v1/residents:
    post:
      x-internal: true
      deprecated: true
      summary: Create a resident (v1, deprecated)
      tags:
      - Residents (deprecated)
      description: 'Creates a v1 resident document. Prefer `POST /v2/residents`, which uses the richer

        tenant model and a structured request body. The v1 request uses the resident shape

        `first_name`, `last_name`, `emails`, and `current_property_id` (see

        `resident_create_request_model`).

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resident_create_request_model'
      responses:
        '200':
          description: Returns the created resident.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/resident_response_model'
        '400':
          description: "Bad request — request body failed validation. Possible messages:\n  - `first_name is missing`, `last_name is missing`, `emails is missing`,\n    `current_property_id is missing` (required fields)\n  - `first_name can not be empty`, `last_name can not be empty`,\n    `current_property_id can not be empty` (whitespace-only values)\n  - `phone_numbers must be an array` (`phone_numbers` is supplied but\n    isn't an array)\n  - `emails has an invalid value: empty` (`emails` is supplied as a\n    non-array or empty array)\n  - `email has an invalid value: <value>` (an email fails format\n    validation)\n  - `phone number has an invalid value: <value>` (a phone number fails\n    format validation)\n  - `current_lease_start has an invalid value` /\n    `current_lease_end has an invalid value` /\n    `move_out_date has an invalid value`\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    example: first_name is missing
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found — `user not found` or `property not found`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    enum:
                    - user not found
                    - property not found
                    example: property not found
  /v1/residents/{residentId}:
    get:
      x-internal: true
      deprecated: true
      summary: Get a resident by ID (v1, deprecated)
      tags:
      - Residents (deprecated)
      description: 'Returns a single v1 resident by id. Prefer the v2 (`/v2/residents/{id}`) and v3

        (`/v3/residents`) endpoints, which return the richer tenant + occupancies model.

        '
      parameters:
      - name: residentId
        in: path
        description: Resident ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the requested resident.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/resident_response_model'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found — `resident not found`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    example: resident not found
    put:
      x-internal: true
      deprecated: true
      summary: Update a resident (v1, deprecated)
      tags:
      - Residents (deprecated)
      description: 'Updates a v1 resident document. Prefer `PUT /v2/residents/{id}` for new integrations.

        '
      parameters:
      - name: residentId
        in: path
        description: Resident ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resident_update_request_model'
      responses:
        '200':
          description: Returns the updated resident.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/resident_response_model'
        '400':
          description: "Bad request — request body failed validation. Possible messages:\n  - `emails has an invalid value: empty` (empty or non-array `emails`)\n  - `email has an invalid value: <value>` (an email fails format validation)\n  - `phone_numbers must be an array`\n  - `phone number has an invalid value: <value>` (a phone number fails format validation)\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    example: 'emails has an invalid value: empty'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found — `resident not found`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    example: resident not found
  /v1/zapier/residents:
    post:
      x-internal: true
      summary: Create a resident from a Zapier trigger
      tags:
      - Residents (deprecated)
      description: 'Zapier-flavoured entry point for the v1 resident create flow. The Zapier

        request body carries a single flat resident payload; the property is

        resolved by (`address` + `postal_code`) within the caller''s user +

        organizations and the request is then delegated to the v1 resident

        create flow. The response payload mirrors the classic

        `resident_response_model`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/zapier_resident_create_request_model'
      responses:
        '200':
          description: Returns the created resident.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/resident_response_model'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: 'Not Found — no property matched the supplied `address` +

            `postal_code` within the caller''s user + organizations.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    enum:
                    - Property not found
                    example: Property not found
        '409':
          description: 'Conflict — a resident with the supplied email already exists on a

            property owned by the caller.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  error:
                    type: string
                    example: Resident already exists
components:
  schemas:
    resident_create_request_model:
      type: object
      required:
      - current_property_id
      - first_name
      - last_name
      - emails
      properties:
        current_property_id:
          type: string
          description: The entity id of the latest Unit occupied by the Resident.
          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
        emails:
          type: array
          description: Resident's emails
          items:
            type: string
          example:
          - resident@email.com
        phone_numbers:
          type: array
          items:
            type: string
          description: Resident's phone numbers
          example:
          - '+17035556390'
        current_lease_start:
          type: string
          description: The date the Resident's current lease starts.
          example: 2021-01-15 00:00:00
        current_lease_end:
          type: string
          description: The date the Resident's current lease should end.
          example: 2022-01-15 00:00:00
        current_rent:
          type: number
          description: The dollar amount of the Resident's current rent. Must be ≥ 0.
          example: 100
        current_security_deposit:
          type: number
          description: The dollar amount of the Resident's security deposit. Must be ≥ 0.
          example: 150
        move_out_date:
          type: string
          description: The date that the Resident is scheduled to move out of the current Property.
          example: 2022-01-15 00:00:00
        previous_properties:
          type: array
          description: Always emitted as an empty array on v1 resident responses. To enumerate the past leases for a resident, list them via `GET /v2/residents/{residentId}/leases`. Retained here for backward compatibility.
          items:
            type: string
            description: Entity ID
            example: 00BRcZPSakXz6w7RYoE
    resident_update_request_model:
      type: object
      properties:
        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
        emails:
          type: array
          description: Resident's emails
          items:
            type: string
          example:
          - resident@email.com
        phone_numbers:
          type: array
          items:
            type: string
          description: Resident's phone numbers
          example:
          - '+17035556390'
    zapier_resident_create_request_model:
      x-internal: true
      type: object
      required:
      - address
      - postal_code
      - first_name
      - last_name
      - email
      properties:
        address:
          type: string
          description: Street address of the resident's current property. Combined with `postal_code` to locate the property owned by the caller's user or organizations.
        postal_code:
          type: string
          description: Postal code (ZIP) matching the property being looked up.
        first_name:
          type: string
          description: Resident's first name.
        last_name:
          type: string
          description: Resident's last name.
        email:
          type: string
          format: email
          description: Resident's email address. Used both to check for an existing resident record on the property and as the primary contact email on the created resident.
        phone_number:
          type: string
          description: Optional single phone number, added as the sole entry in the resident's `phone_numbers` array.
        lease_start_date:
          type: string
          description: Optional ISO-8601 lease start date.
        lease_end_date:
          type: string
          description: Optional ISO-8601 lease end date.
        monthly_rent:
          type: number
          description: Optional monthly rent amount for the lease.
        security_deposit:
          type: number
          description: Optional security deposit amount for the lease.
    resident_response_model:
      type: object
      required:
      - id
      - organizationID
      - emails
      - previous_properties
      - created_date
      - updated_date
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        user_id:
          type: string
          description: The id of the linked user account for this resident, when one exists. Populated once the resident accepts an invite and signs in.
          example: 00BRcZPSakXz6w7RYoE
        organizationID:
          type: string
          description: The id of the organization that owns the resident record.
          example: 00BRcZPSakXz6w7RYoE
        owner_id:
          type: string
          description: User ID of the resident entity
          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
        emails:
          type: array
          description: Resident's emails
          items:
            type: string
          example:
          - resident@email.com
        phone_numbers:
          type: array
          items:
            type: string
          description: Resident's phone numbers
          example:
          - '+17035556390'
        current_property_id:
          type: string
          description: The entity id of the latest Unit occupied by the Resident.
          example: 00BRcZPSakXz6w7RYoE
        current_property_address:
          type: string
          description: This field is the street address from the property listed in the inspection
          example: 1234 Street name
        current_lease_start:
          type: string
          description: The date the Resident's current lease starts.
          example: 2021-01-15 00:00:00
        current_lease_end:
          type: string
          description: The date the Resident's current lease should end.
          example: 2022-01-15 00:00:00
        current_rent:
          type: number
          description: The dollar amount of the Resident's current rent. Must be ≥ 0.
          example: 100
        current_security_deposit:
          type: number
          description: The dollar amount of the Resident's security deposit. Must be ≥ 0.
          example: 150
        move_out_date:
          type: string
          description: The date that the Resident is scheduled to move out of the current Property.
          example: 2022-01-15 00:00:00
        previous_properties:
          type: array
          description: Always emitted as an empty array on v1 resident responses. To enumerate the past leases for a resident, list them via `GET /v2/residents/{residentId}/leases`. Retained here for backward compatibility.
          items:
            type: string
            description: Entity ID
            example: 00BRcZPSakXz6w7RYoE
        creation_source:
          type: string
          description: App that perform the entity creation.
          enum:
          - zapier
          - rentmanager
          - flatfile
          - 365connect
          - appfolio
          - yardi
          - rentvine
          - test_app_id
          example: zapier
        created_date:
          type: string
          description: Entity creation date, in ISO format
          example: 2022-12-02 14:15:37.925000
        updated_date:
          type: string
          description: Entity last update date, in ISO format
          example: 2023-10-04 14:15:37.925000
  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