RentCheck Permission Groups API

openapi: 3.2.0
info:
  title: RentCheck REST Permission Groups 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: Permission Groups
paths:
  /v1/permission-groups:
    post:
      summary: Create permission group
      tags:
      - Permission Groups
      description: This resource allows you to create a Permission Group in RentCheck.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permission_group_create_request_model'
      responses:
        '201':
          description: Returns the created permission group
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 201
                  data:
                    $ref: '#/components/schemas/api_permission_group'
        '400':
          description: Bad request — request body validation failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - '"data.name" is required'
                    - '"data.inspection_template_ids" is required'
                    - '"data.allow_billing_plan_editing" is required'
                    - '"data.user_ids" is required'
                    example: '"data.name" is required'
        '401':
          description: 'Unauthorized — either a standard auth-token failure, or the caller''s

            role does not allow creating permission groups. When the role is

            insufficient, the request surfaces as 401 with the error string below.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    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
                    - User does not have permissions to create permission group
                    example: User does not have permissions to create permission group
        '404':
          description: 'Not Found — `subscription not found` (caller has no active

            subscription), `inspection template not found (<id>)`, or

            `user not found (<id>)` when one of the supplied `user_ids` /

            `inspection_template_ids` does not resolve.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    enum:
                    - subscription not found
                    - inspection template not found (<id>)
                    - user not found (<id>)
                    example: subscription not found
        '409':
          description: 'Conflict — a permission group with the requested `name` already exists

            on the caller''s subscription (names are unique per subscription).

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  error:
                    type: string
                    example: A permission group with this name already exists on the subscription
      operationId: postV1PermissionGroups
      x-operation-id-source: derived
    delete:
      summary: Delete permission groups
      tags:
      - Permission Groups
      description: 'Bulk-delete permission groups belonging to the caller''s subscription. Group ids are passed in the

        request body (not the URL); at least one permission group must remain on the subscription after

        the operation, so attempting to delete every remaining group is rejected with a 403.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permission_group_delete_request_model'
      responses:
        '204':
          description: Successful deletion of permission groups.
        '400':
          description: 'Bad request — validation rejected the body. `data.ids` must be a

            non-empty string array, so both a missing field and an empty array

            surface here.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - '"data.ids" is required'
                    - '"data.ids" must contain at least 1 items'
                    example: '"data.ids" is required'
        '401':
          description: 'Unauthorized — either a standard auth-token failure, or the caller''s

            role does not allow deleting permission groups.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    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
                    - User does not have permissions to delete permission group
                    example: User does not have permissions to delete permission group
        '403':
          description: Forbidden — the delete would leave the subscription with no remaining permission groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 403
                  error:
                    type: string
                    enum:
                    - At least one permission group must remain on the subscription
                    example: At least one permission group must remain on the subscription
        '404':
          description: 'Not Found — `subscription not found`, or `permission group not found (<id>)`.

            The permission-group message includes the offending id in parentheses,

            i.e. `<name> not found (<id>)`.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    example: permission group not found (abc123)
      operationId: deleteV1PermissionGroups
      x-operation-id-source: derived
    get:
      summary: Get all permission groups
      tags:
      - Permission Groups
      description: This resource fetches all Permission Groups associated with the user's subscription.
      parameters:
      - in: query
        name: filters[search]
        description: Search by permission group name or id.
        schema:
          type: string
      - in: query
        name: filters[user_id]
        description: Restrict results to permission groups that include the given user id.
        schema:
          type: string
      - 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: Page number (zero-indexed).
        schema:
          type: integer
          default: 0
      - in: query
        name: options[sort][sort_type]
        description: Sort list in ascending or descending order.
        schema:
          type: string
          default: ASC
          enum:
          - ASC
          - DESC
      - in: query
        name: options[sort][sort_by]
        description: Sort list by a specific property.
        schema:
          type: string
          default: name
          enum:
          - name
          - user_count
      responses:
        '200':
          description: Returns all permission groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/permission_group_get_all_response_model'
                  count:
                    type: integer
                    description: Amount of elements in `data` on the current page.
                  total_results:
                    type: integer
                    description: Total amount of permission groups matching the filter criteria (irrespective of paging).
        '401':
          $ref: '#/components/responses/401'
      operationId: getV1PermissionGroups
      x-operation-id-source: derived
  /v1/permission-groups/{id}:
    get:
      summary: Get permission group by ID
      tags:
      - Permission Groups
      description: This resource allows you to get a Permission Group in RentCheck.
      parameters:
      - name: id
        in: path
        description: Permission group ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the requested permission group
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/api_permission_group'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found — `subscription not found` (when the caller has no subscription) or `permission group not found`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    enum:
                    - subscription not found
                    - permission group not found
                    example: permission group not found
      operationId: getV1PermissionGroupsById
      x-operation-id-source: derived
    put:
      summary: Update permission group
      tags:
      - Permission Groups
      description: This resource allows you to update a Permission Group in RentCheck.
      parameters:
      - name: id
        in: path
        description: Permission group ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permission_group_update_request_model'
      responses:
        '200':
          description: Returns the updated permission group
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 200
                  data:
                    $ref: '#/components/schemas/api_permission_group'
        '400':
          description: Bad request — validation rejected the request body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  error:
                    type: string
                    enum:
                    - '"data.name" is required'
                    - '"data.inspection_template_ids" is required'
                    - '"data.user_ids" is required'
                    example: '"data.name" is required'
        '401':
          description: 'Unauthorized — either a standard auth-token failure, or the caller''s

            role does not allow updating permission groups. When the role is

            insufficient, the request surfaces as 401 with the error string below.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  error:
                    type: string
                    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
                    - User does not have permissions to update permission group
                    example: User does not have permissions to update permission group
        '404':
          description: 'Not Found — `subscription not found`, `permission group not found`,

            `user not found (<id>)`, or `inspection template not found (<id>)`.

            The `user` and `inspection template` messages include the offending

            id in parentheses, i.e. `<name> not found (<id>)`.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  error:
                    type: string
                    example: user not found (abc123)
        '409':
          description: 'Conflict — a different permission group already owns the requested

            `name` on the caller''s subscription (names are unique per

            subscription). Renaming to the current name is not a conflict.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  error:
                    type: string
                    example: A permission group with this name already exists on the subscription
      operationId: putV1PermissionGroupsById
      x-operation-id-source: derived
components:
  schemas:
    permission_group_create_request_model:
      type: object
      required:
      - name
      - inspection_template_ids
      - user_ids
      - allow_billing_plan_editing
      properties:
        name:
          type: string
          description: Name for the permission group, must be unique in the subscription context
        allow_billing_plan_editing:
          type: boolean
          description: Enable or disable billing plan editing for users on this permission group
        allow_automation_editing:
          type: boolean
          description: Enable or disable automation editing for users on this permission group
        allow_notifications_preferences_editing:
          type: boolean
          description: Enable or disable notification preferences editing for users on this permission group
        allow_inspection_messaging_editing:
          type: boolean
          description: Enable or disable inspection messaging editing for users on this permission group
        allow_ai_manual_scan:
          type: boolean
          description: Enable or disable manual AI damage scans for users on this permission group
        inspection_template_ids:
          type: array
          items:
            type: string
          description: IDs of the inspection templates to be associated with the new permission group
        user_ids:
          type: array
          items:
            type: string
          description: IDs of the users to be associated with the new permission group
    permission_group_update_request_model:
      type: object
      required:
      - name
      - inspection_template_ids
      - user_ids
      - allow_billing_plan_editing
      properties:
        name:
          type: string
          description: Name for the permission group, must be unique in the subscription context
        inspection_template_ids:
          type: array
          items:
            type: string
          description: IDs of the inspection templates to be associated with the permission group
        user_ids:
          type: array
          items:
            type: string
          description: IDs of the users to be associated with the permission group
        allow_billing_plan_editing:
          type: boolean
          description: Enable or disable billing plan editing for users on this permission group
        allow_automation_editing:
          type: boolean
          description: Enable or disable automation editing for users on this permission group
        allow_notifications_preferences_editing:
          type: boolean
          description: Enable or disable notification preferences editing for users on this permission group
        allow_inspection_messaging_editing:
          type: boolean
          description: Enable or disable inspection messaging editing for users on this permission group
        allow_ai_manual_scan:
          type: boolean
          description: Enable or disable manual AI damage scans for users on this permission group
    permission_group_get_all_response_model:
      type: object
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        name:
          type: string
          description: Name of the permission group
        user_count:
          type: number
          description: Total amount of users on the permission group
        allow_billing_plan_editing:
          type: boolean
          description: Whether users on this permission group can edit billing plans.
        allow_automation_editing:
          type: boolean
          description: Whether users on this permission group can edit automations.
        allow_notifications_preferences_editing:
          type: boolean
          description: Whether users on this permission group can edit notification preferences.
        allow_inspection_messaging_editing:
          type: boolean
          description: Whether users on this permission group can edit inspection messaging.
        allow_ai_manual_scan:
          type: boolean
          description: Whether users on this permission group can run manual AI damage scans.
    permission_group_delete_request_model:
      type: object
      required:
      - ids
      properties:
        ids:
          type: array
          minItems: 1
          items:
            type: string
          description: IDs of the permission groups to be deleted. Must contain at least one id.
    api_permission_group:
      type: object
      required:
      - id
      - name
      - subscription_id
      - inspection_templates
      - users
      - allow_billing_plan_editing
      - allow_automation_editing
      - allow_notifications_preferences_editing
      - allow_inspection_messaging_editing
      - allow_ai_manual_scan
      properties:
        id:
          type: string
          description: Entity ID
          example: 00BRcZPSakXz6w7RYoE
        name:
          type: string
          description: Name for the permission group, must be unique in the subscription context
        subscription_id:
          type: string
          description: Id for the subscription the permission group belongs to
        allow_billing_plan_editing:
          type: boolean
          description: Enable or disable billing plan editing for users on this permission group
        allow_automation_editing:
          type: boolean
          description: Enable or disable automation editing for users on this permission group
        allow_notifications_preferences_editing:
          type: boolean
          description: Enable or disable notification preferences editing for users on this permission group
        allow_inspection_messaging_editing:
          type: boolean
          description: Enable or disable inspection messaging editing for users on this permission group
        allow_ai_manual_scan:
          type: boolean
          description: Enable or disable manual AI damage scans for users on this permission group
        inspection_templates:
          type: array
          description: Which inspection templates users that belong to this permission group have access to
          items:
            type: object
            required:
            - id
            - name
            - internal_label
            - property_type
            - display_name
            properties:
              id:
                type: string
                description: Inspection template identifier
              name:
                type: string
                description: Inspection template name.
              internal_label:
                type: string
                description: Inspection template internal label.
              property_type:
                type: string
                description: Inspection template property type.
              display_name:
                type: string
                description: Resolved display name for the inspection template, used by clients to render the template title (mirrors `name` for legacy templates).
        users:
          description: Which users belong to this permission group
          type: array
          items:
            properties:
              id:
                type: string
                description: Entity ID
                example: 00BRcZPSakXz6w7RYoE
              name:
                type: string
                description: Name of the user
              email:
                type: string
                description: Email of the user
              type:
                type: string
                enum:
                - Renter
                - Property Manager
                - Landlord
                - System
                description: User type discriminator.
              user_type:
                type: string
                enum:
                - Renter
                - Property Manager
                - Landlord
                example: Property Manager
  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