RentCheck Work Orders API

openapi: 3.2.0
info:
  title: RentCheck REST Work Orders API
  version: 1.0.0
  description: '## Mission

    At RentCheck, our mission is plain and simple: To make renting fair and transparent for everyone involved.'
  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
      operationId: postV1WorkOrdersProvidersByProvider
      x-operation-id-source: derived
  /v1/work_orders/{workOrderId}:
    get:
      x-internal: true
      summary: Get a work order by ID
      tags:
      - Work Orders
      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
      operationId: getV1WorkOrdersByWorkOrderId
      x-operation-id-source: derived
  /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'
      operationId: getV1WorkOrdersSkills
      x-operation-id-source: derived
components:
  schemas:
    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_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_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
    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
    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_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
  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