RentCheck Work Orders API

openapi: 3.1.0
info:
  title: RentCheck REST Account Settings Work Orders 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: Work Orders
paths:
  /v1/work_orders/providers/{provider}:
    post:
      x-internal: true
      summary: Create a work order
      tags:
      - Work Orders
      description: 'Creates a Work Order in RentCheck and dispatches it to the requested

        integration provider. The path parameter `provider` selects the

        destination integration; the request body shape varies per provider.

        '
      parameters:
      - in: path
        name: provider
        required: true
        schema:
          type: string
          enum:
          - appfolio
          - jenark
          - latchel
          - rentmanager
          - rentvine
        description: 'The integration provider that should fulfill this work order.

          '
      - in: header
        name: x-app-id
        required: false
        description: 'Creation-source identifier. Persisted as `creation_source` on each

          created work order.

          '
        schema:
          type: string
      requestBody:
        required: true
        description: "Request body shape varies per `{provider}`. The provider in the path\ndetermines which validation runs against the body:\n  * `latchel`, `rentmanager`, `jenark` — the body is validated against\n    the provider-specific schema.\n  * `appfolio` / `rentvine` — the body is forwarded to the integration\n    provider without additional validation.\n"
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/work_order_create_latchel_request_model'
              - $ref: '#/components/schemas/work_order_create_rent_manager_request_model'
              - $ref: '#/components/schemas/work_order_create_jenark_request_model'
              - $ref: '#/components/schemas/work_order_create_appfolio_request_model'
              - $ref: '#/components/schemas/work_order_create_rentvine_request_model'
      responses:
        '200':
          description: Returns the created work order
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/work_order_response_model'
        '400':
          description: "Bad request — request body validation failed, or the supplied\nfeatures span more than one inspection. Validation messages are raw, e.g.:\n  - `\"data.work_order_name\" is required`\n  - `\"data.work_order_description\" is required`\n  - `\"data.maintenance_flags\" must contain at least 1 items`\n  - `\"data.maintenance_flags\" must be an array`\n  - `\"data.latchel_property_id\" is required` (`latchel`)\n  - `\"data.ok_to_enter\" is required` (`rentmanager`)\n  - `\"data.priority\" must be one of [Low, Normal, High]` (`rentmanager`)\n  - `\"data.work_order_code\" is required` (`jenark`)\nThe cross-inspection guard returns\n`Inspection must be consistent. All features should belong to the same inspection.`\nThe Rent Manager integration also surfaces\n`property not synced with integration` and\n`No rentmanager integration is configured for this account` as 400\nwhen its preflight checks fail.\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
        '401':
          description: 'Unauthorized — standard auth failures, plus the per-work-order permission check

            (`User does not have permissions to create work order` is emitted as 401,

            not 400).

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    example: User does not have permissions to create work order
        '404':
          description: 'Not Found — `subscription not found` (caller has no subscription),

            `appfolio integration not found`, `rentvine integration not found`,

            `latchel integration not found` (the destination integration is not

            configured for the caller''s subscription), `resident not found (<id>)`

            (the supplied `resident_id` does not exist), or `property not found`

            (the property associated with the flagged features is not synced to

            the requested integration).

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    description: 'One of the static integration / subscription / property

                      not-found strings, OR `resident not found (<id>)` carrying

                      the supplied resident id.

                      '
                    oneOf:
                    - enum:
                      - subscription not found
                      - appfolio integration not found
                      - rentvine integration not found
                      - latchel integration not found
                      - property not found
                    - pattern: ^resident not found \(.+\)$
                    example: appfolio integration not found
        '500':
          description: "Internal server error. Sources:\n  - Unknown `provider` — `invalid provider` is returned when the path\n    parameter is not one of the registered providers. The\n    path-parameter `enum` documents the supported set; unsupported\n    providers should be rejected before processing.\n  - Jenark — `property not synced with Jenark` is returned when the\n    property is not synced through the Jenark integration. (The\n    analogous Rent Manager check surfaces as 400 — see the 400\n    response above.)\n  - AppFolio / Rentvine — `Must have work order sync switched ON in\n    order to create work orders. Please adjust your data sync\n    settings.` is returned when the integration exists but work-order\n    sync is disabled.\n"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 500
                  error:
                    type: string
                    enum:
                    - invalid provider
                    - property not synced with Jenark
                    - Must have work order sync switched ON in order to create work orders. Please adjust your data sync settings.
                    example: invalid provider
  /v1/work_orders/{workOrderId}:
    get:
      x-internal: true
      summary: Get a work order by ID
      tags:
      - Work Orders
      description: Get a work order by ID
      parameters:
      - name: workOrderId
        in: path
        description: work order ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the requested work order
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/work_order_response_model'
        '401':
          description: 'Unauthorized — standard auth failures, plus the per-work-order permission check.

            Returns HTTP 401 with message `User does not have permissions to get work order` when

            the caller''s role doesn''t allow read access.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    example: User does not have permissions to get work order
        '404':
          description: Not Found — `work order not found`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    example: work order not found
  /v1/work_orders/skills:
    get:
      x-internal: true
      summary: Get all work order skills
      tags:
      - Work Orders
      description: 'Returns the list of skills that can be selected when creating a work order. The

        same static list is always returned, regardless of the caller''s enabled integrations.

        '
      responses:
        '200':
          description: Returns the list of work order skills.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/api_work_order_skill'
                  count:
                    type: integer
                    description: Amount of elements in `data`.
        '401':
          $ref: '#/components/responses/401'
components:
  schemas:
    work_order_create_latchel_request_model:
      x-internal: true
      type: object
      required:
      - work_order_name
      - work_order_description
      - maintenance_flags
      - latchel_property_id
      properties:
        work_order_name:
          type: string
          description: A name / label for the work order.
          example: 'Latchel Job #1'
        work_order_description:
          type: string
          description: A description for the work order.
          example: Faulty socket, no power, needs repair.
        vendor_instructions:
          type: string
          description: Optional vendor instruction for the work order.
          example: Use your biggest plunger, do not use little plunger.
        skill:
          type: string
          description: Vendor name of the repair to be made.
          example: Repair socket
        property_access_instructions:
          type: string
          description: Property access instructions for the work order.
          example: Look under the door mat; there is a secret entrance.
        latchel_property_id:
          type: number
          description: Latchel property id for the work order.
        vendor_id:
          type: number
          nullable: true
          description: Latchel vendor id for the work order.
        resident_id:
          type: string
          description: Resident / Tenant ID that will be associated with work order.
        primary_resident_id:
          type: string
          description: Latchel primary resident id for the work order.
        maintenance_flags:
          type: array
          minItems: 1
          description: A list of maintenance flags. Only each flag's `id` and `feature_id` are consumed; additional fields are accepted but ignored.
          items:
            type: object
            required:
            - id
            - feature_id
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              feature_id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
            additionalProperties: true
    work_order_create_appfolio_request_model:
      x-internal: true
      type: object
      description: AppFolio work-order create body. Additional AppFolio-specific properties beyond those listed here are accepted.
      required:
      - work_order_name
      - work_order_description
      - maintenance_flags
      - ok_to_enter
      properties:
        work_order_name:
          type: string
          description: A name / label for the work order.
        work_order_description:
          type: string
          description: A description for the work order.
        priority:
          type: string
          enum:
          - Urgent
          - Normal
          - Low
          description: AppFolio priority for the work order.
        ok_to_enter:
          type: boolean
          description: Whether the vendor is authorized to enter the unit without the resident present.
        maintenance_flags:
          type: array
          minItems: 1
          items:
            type: object
            required:
            - id
            - feature_id
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              feature_id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
            additionalProperties: true
      additionalProperties: true
    work_order_create_rent_manager_request_model:
      x-internal: true
      type: object
      required:
      - work_order_name
      - work_order_description
      - maintenance_flags
      - ok_to_enter
      properties:
        work_order_name:
          type: string
          description: A name / label for the work order.
          example: Leaky faucet repair
        work_order_description:
          type: string
          description: A description for the work order.
          example: Faucet in kitchen is dripping — please replace washer.
        skill:
          type: string
          description: Trade / skill required for the work order.
          example: Plumbing
        priority:
          type: string
          enum:
          - Low
          - Normal
          - High
          description: Rent Manager work-order priority.
        ok_to_enter:
          type: boolean
          description: Whether the vendor is authorized to enter the unit without the resident present.
        maintenance_flags:
          type: array
          minItems: 1
          description: A list of maintenance flags. The handler only consumes each flag's `id` and `feature_id`; additional fields are accepted but ignored.
          items:
            type: object
            required:
            - id
            - feature_id
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              feature_id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
            additionalProperties: true
    work_order_create_jenark_request_model:
      x-internal: true
      type: object
      required:
      - work_order_name
      - work_order_code
      - maintenance_flags
      properties:
        work_order_name:
          type: string
          description: A name / label for the work order.
          example: Replace HVAC filter
        work_order_description:
          type: string
          description: A description for the work order.
          example: Filter is overdue — replace with 16x20x1 pleated filter.
        work_order_code:
          type: string
          description: Jenark work-order classification code.
          example: HVAC
        skill:
          type: string
          description: Trade / skill required for the work order.
          example: HVAC
        maintenance_flags:
          type: array
          minItems: 1
          description: A list of maintenance flags. The handler only consumes each flag's `id` and `feature_id`; additional fields are accepted but ignored.
          items:
            type: object
            required:
            - id
            - feature_id
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              feature_id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
            additionalProperties: true
    api_work_order_skill:
      type: object
      required:
      - name
      - latchel
      properties:
        name:
          type: string
          description: RentCheck-facing name of the skill.
        latchel:
          type: object
          description: Latchel category mapping for the skill.
          required:
          - id
          - name
          - category_id
          - category_name
          properties:
            id:
              type: integer
              description: Latchel skill id.
            name:
              type: string
              description: Latchel-facing skill name.
            category_id:
              type: integer
              description: Latchel category id.
            category_name:
              type: string
              description: Latchel category name.
    work_order_create_rentvine_request_model:
      x-internal: true
      type: object
      description: Rentvine work-order create body. Additional Rentvine-specific properties beyond those listed here are accepted.
      required:
      - work_order_name
      - work_order_description
      - priority
      - ok_to_enter
      properties:
        work_order_name:
          type: string
          description: A name / label for the work order.
        work_order_description:
          type: string
          description: A description for the work order.
        priority:
          type: string
          enum:
          - low
          - medium
          - high
          description: Rentvine priority for the work order.
        owner_approved:
          type: boolean
          default: false
          description: Whether the property owner has approved the work order in Rentvine. Server-defaulted to `false` when omitted.
        publish_with_tenant:
          type: boolean
          default: false
          description: Whether the work order should be published to the Rentvine tenant portal. Server-defaulted to `false` when omitted.
        publish_with_owner:
          type: boolean
          default: false
          description: Whether the work order should be published to the Rentvine owner portal. Server-defaulted to `false` when omitted.
        ok_to_enter:
          type: string
          enum:
          - vendor_may_access
          - resident_presence_required
          - not_applicable
          description: Vendor access mode.
        maintenance_flags:
          type: array
          description: Maintenance flags referenced by the work order. No minimum size is enforced by validation, but omitting it or passing an empty array surfaces as a 500.
          items:
            type: object
            required:
            - id
            - feature_id
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              feature_id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
            additionalProperties: true
      additionalProperties: true
    work_order_response_model:
      x-internal: true
      type: object
      description: Envelope shared by v1 (`POST /v1/work_orders`) and v2 (`GET /v2/work_orders`). Provider-specific keys (`latchel`, `yardi`, `appfolio`, `jenark`, `rentmanager`, `rentvine`) remain optional and appear only when the work order was synced through that vendor. `property` is required on v1 responses; v2 (`GET /v2/work_orders`) drops the field when the underlying row has no property snapshot, so it is not listed as required here.
      required:
      - id
      - name
      - created_date
      - created_by
      - created_by_name
      - status
      - maintenance_flags
      - organization_id
      - inspection
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        name:
          type: string
          description: The name field is the work order name / label.
          example: 'Latchel Job #1'
        created_date:
          type: string
          description: Work order creation date, ISO format.
          example: 2022-01-15 00:00:00
        created_by:
          type: string
          description: User id that created the work order.
        created_by_name:
          type: string
          description: Display name of the user that created the work order.
        organization_id:
          type: string
          description: Organization (subscription) the work order belongs to.
        status:
          type: string
          description: Up to date status of the work order.
        skill:
          type: string
          description: Skill / category selected for the work order.
        zip_report_location:
          type: string
          description: Location of the most recent generated zip report for the work order. Only present on v2 (`GET /v2/work_orders`) responses; v1 responses do not emit this field.
        last_sync_date:
          type: string
          description: ISO timestamp of the latest sync attempt to the work order provider, when one has run. Only present on v2 (`GET /v2/work_orders`) responses; v1 responses do not emit this field.
        inspection:
          type: object
          description: This is the entity id of the inspection that the entity is for.
          properties:
            id:
              type: string
              description: Selected entity's inspection id
              example: 00BRcZPSakXz6w7RYoE
            type:
              type: string
              description: Selected entity's inspection type
              enum:
              - Move-in
              - Move-out
              - Annual
              - Turn
              - Periodic
              - Maintenance Check
              - Exterior
              - Pre-Acquisition
              - RV Lot
              - Maintenance / Safety Check
              - Community Maintenance Check
            date:
              type: string
              description: Selected entity's inspection date, ISO format
              example: 2022-01-15 00:00:00
            template:
              type: object
            completed_date:
              type: string
              description: Inspection completed date in ISO format, when set.
        property:
          type: object
          required:
          - id
          - address
          - city
          - zip_code
          description: This is the entity id of the Unit, Building, or Community that the entity is for.
          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
            address_2:
              type: string
              description: Selected entity's property additional address info
              example: Apt. 4B
            city:
              type: string
              description: Selected entity's property city
              example: New Orleans
            region:
              type: string
              description: Selected entity's property region
              example: Orleans
            zip_code:
              type: string
              description: Selected entity's property zip_code
              example: '70130'
        maintenance_flags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              room:
                type: string
                description: Maintenance flag's room.
              feature:
                type: string
                description: Maintenance flag's feature name.
              feature_id:
                type: string
                description: Maintenance flag's feature ID.
              created_date:
                type: string
                description: Feature creation date, ISO format
                example: 2022-01-15 00:00:00
              created_by:
                type: object
                description: User that created the flag.
                required:
                - id
                - name
                - type
                properties:
                  id:
                    type: string
                    description: Entity ID
                    example: 00BRcZPSakXz6w7RYoE
                  name:
                    type: string
                    description: Name of the user that created the flag.
                  type:
                    type: string
                    enum:
                    - Renter
                    - Property Manager
                    - Landlord
                    - System
                    description: User type discriminator.
              responsibility:
                type: string
                description: Maintenance flag's responsibility
                enum:
                - OWNER
                - RESIDENT
                - ''
              note:
                type: string
                description: Maintenance flag's notes
              image_urls:
                type: array
                description: Maintenance flag's images
                items:
                  type: string
                  description: URL links to images related to the maintenance flags
              cost:
                type: number
                description: Maintenance flag's cost
        latchel:
          type: object
          description: Latchel-specific work order fields, present when the provider is `latchel`.
          additionalProperties: true
        yardi:
          type: object
          description: Yardi-specific work order fields, present when the provider is `yardi`.
          additionalProperties: true
        appfolio:
          type: object
          description: AppFolio-specific work order fields, present when the provider is `appfolio`.
          additionalProperties: true
        jenark:
          type: object
          description: Jenark-specific work order fields, present when the provider is `jenark`.
          additionalProperties: true
        rentmanager:
          type: object
          description: Rent Manager-specific work order fields, present when the provider is `rentmanager`.
          additionalProperties: true
        rentvine:
          type: object
          description: Rentvine-specific work order fields, present when the provider is `rentvine`.
          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