Rentberry Rental API

openapi: 3.2.0
info:
  title: Rentberry Rental API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Rental
  description: Rental
paths:
  /v{version}/rental:
    get:
      tags:
      - Rental
      summary: Get list of user rentals.
      description: Returns paginated list of rentals for the authenticated user. Available since API version 1.
      operationId: get_api_v1_application_rentals_list
      parameters:
      - name: limit
        in: query
        description: Number of items per page
        schema:
          type: integer
          default: 9
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of rentals returned successfully.
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
    post:
      tags:
      - Rental
      summary: Create a new rental.
      description: Creates a new rental and sends invitation to tenant. Available since API version 1.
      operationId: post_api_v1_rental_create
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentalType'
      responses:
        '200':
          description: Rental created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rental'
        '400':
          description: Validation failed.
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
  /v{version}/rental/chargeable/{userType}:
    get:
      tags:
      - Rental
      summary: Get list of chargeable rentals.
      description: Returns paginated list of chargeable rentals for tenant or homeowner. Available since API version 1.
      operationId: get_api_v1_chargeable_rentals_list
      parameters:
      - name: userType
        in: path
        description: User type (tenant or homeowner)
        required: true
        schema:
          type: string
          default: tenant
          pattern: tenant|homeowner
          enum:
          - tenant
          - homeowner
      - name: archived
        in: query
        description: Include archived rentals
        schema:
          type: boolean
          default: false
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of chargeable rentals returned successfully.
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
  /v{version}/rental/{id}:
    get:
      tags:
      - Rental
      summary: Get rental details.
      description: Returns detailed information about a specific rental. Available since API version 1.
      operationId: get_api_v1_rental_get
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Rental details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rental4'
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental.
      security:
      - XAuthToken: []
    post:
      tags:
      - Rental
      summary: Update an existing rental.
      description: Updates rental information. Available since API version 1.
      operationId: post_api_v1_rental_update
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentalType'
      responses:
        '200':
          description: Rental updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rental'
        '400':
          description: Validation failed.
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental.
      security:
      - XAuthToken: []
  /v{version}/rental/activate/{reference}:
    get:
      tags:
      - Rental
      summary: Activate rental by tenant.
      description: Activates rental using reference code when tenant accepts invitation. Available since API version 1.
      operationId: get_api_v1_rental_activate
      parameters:
      - name: reference
        in: path
        description: Rental reference code
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Rental activated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rental'
        '401':
          description: Unauthorized
        '404':
          description: Rental not found or invalid reference.
        '409':
          description: Cannot activate rental in current status.
      security:
      - XAuthToken: []
  /v{version}/rental/archive/{rental}:
    post:
      tags:
      - Rental
      summary: Archive a rental.
      description: Archives rental and changes its status. Available since API version 1.
      operationId: post_api_v1_rental_archive
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: rental
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rental archived successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rental'
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental.
      security:
      - XAuthToken: []
  /v{version}/rental/invite-homeowner:
    post:
      tags:
      - Rental
      summary: Send invitation to homeowner.
      description: Sends email invitation to potential homeowner. Available since API version 1.
      operationId: post_api_v1_rental_invite_homeowner
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteHomeownerType'
      responses:
        '204':
          description: Invitation sent successfully.
        '400':
          description: Validation failed.
        '401':
          description: Unauthorized
  /v{version}/rental/invite-tenant/{rental}:
    post:
      tags:
      - Rental
      summary: Resend invitation to tenant.
      description: Resends email invitation to tenant for rental. Available since API version 1.
      operationId: post_api_v1_rental_invite_tenant
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: rental
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Invitation resent successfully.
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental.
      security:
      - XAuthToken: []
  /v{version}/rental/list:
    get:
      tags:
      - Rental
      summary: Get short list of user rentals.
      description: Returns simplified list of rentals for the authenticated user. Available since API version 1.
      operationId: get_api_v1_rental_list_short
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Short list of rentals returned successfully.
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
  /v{version}/rental/{id}/document:
    post:
      tags:
      - Rental
      summary: Upload document to rental.
      description: Uploads and attaches document to rental. Available since API version 1.
      operationId: post_api_v1_rental_add_document
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  type: string
                  format: binary
              type: object
      responses:
        '200':
          description: Document uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDocument'
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental.
      security:
      - XAuthToken: []
  /v{version}/rental/{id}/document/download/{document}:
    get:
      tags:
      - Rental
      summary: Download rental document.
      description: Downloads document attached to rental. Available since API version 1.
      operationId: get_api_v1_rental_download_document
      parameters:
      - name: document
        in: path
        description: Document ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Document downloaded successfully.
          content:
            application/octet-stream: []
        '401':
          description: Unauthorized
        '403':
          description: Access denied to rental or document.
        '404':
          description: Document not found.
      security:
      - XAuthToken: []
components:
  schemas:
    Bounds:
      properties:
        northeast:
          $ref: '#/components/schemas/Coordinates'
        southwest:
          $ref: '#/components/schemas/Coordinates'
      type: object
    RentalPaymentUnit:
      properties:
        paymentAmount:
          type: string
        id:
          type: integer
        type:
          type: string
        amount:
          type: string
      type: object
    ApplicantAttachment:
      properties:
        id:
          type: integer
        fileName:
          type: string
        mimeType:
          type: string
        size:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    ApplicantReference2:
      required:
      - name
      - relationship
      - phone
      properties:
        id:
          type: integer
        applicant:
          $ref: '#/components/schemas/Applicant4'
        name:
          type: string
          maxLength: 255
          minLength: 1
        relationship:
          type: string
          maxLength: 255
          minLength: 1
        email:
          type: string
        phone:
          type: integer
          maxLength: 15
          minLength: 7
      type: object
    UserStripeCustomer6:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User6'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    UserRentalHistory2:
      required:
      - address
      - city
      - homeownerPhone
      properties:
        id:
          type: integer
        user:
          $ref: '#/components/schemas/User6'
        applicantId:
          type: integer
        address:
          type: string
          maxLength: 255
          minLength: 3
        city:
          type: string
          maxLength: 255
          minLength: 3
        price:
          type: integer
        term:
          type: integer
        homeownerPhone:
          type: integer
          maxLength: 15
          minLength: 7
      type: object
    UserCreditScore:
      properties:
        score:
          type: integer
        creditScoreUpdatedAt:
          type: string
          format: date-time
        alert:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    ListingApplication4:
      properties:
        deposit:
          type: string
          minimum: 0
        accepted:
          title: for iOs compatibility.
          type: boolean
        declined:
          title: for iOs compatibility.
          type: boolean
        expired:
          title: for iOs compatibility.
          type: boolean
        deleted:
          title: for iOs compatibility.
          type: boolean
        id:
          type: integer
        listing:
          $ref: '#/components/schemas/Listing7'
        price:
          type: string
          minimum: 1
        term:
          type: integer
        moveIn:
          type: string
          format: date-time
        applicants:
          type: array
          items:
            $ref: '#/components/schemas/Applicant4'
        declinedReason:
          type: string
          maxLength: 255
          minLength: 1
        new:
          type: boolean
          default: true
        showNotification:
          type: boolean
          default: false
        status:
          type: string
          default: draft
        notes:
          type: string
          maxLength: 1000
          minLength: 1
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    Applicant4:
      required:
      - employmentType
      properties:
        id:
          type: integer
        user:
          $ref: '#/components/schemas/User6'
        references:
          type: array
          items:
            $ref: '#/components/schemas/ApplicantReference2'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ApplicantAttachment'
        creator:
          type: boolean
          default: false
        active:
          type: boolean
          default: false
        rentalHistory:
          type: array
          items:
            $ref: '#/components/schemas/UserRentalHistory2'
        employmentType:
          type: string
          enum:
          - employed
          - unemployed
          - student
        employmentName:
          type: string
          maxLength: 255
          minLength: 1
        employmentTitle:
          type: string
          maxLength: 255
          minLength: 1
        employmentSourceIncome:
          type: string
          maxLength: 255
          minLength: 1
        employmentIncome:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    User6:
      required:
      - nameFirst
      - nameLast
      - username
      - phone
      properties:
        phoneCountryCode:
          type: string
        id:
          type: integer
        nameFirst:
          type: string
          maxLength: 255
          minLength: 2
        nameMiddle:
          type: string
          maxLength: 255
          minLength: 1
        nameLast:
          type: string
          maxLength: 255
          minLength: 2
        username:
          type: string
          maxLength: 255
          minLength: 1
        profilePictureThumbs:
          type: string
        phone:
          type: string
          maxLength: 15
          minLength: 7
        stripeCustomer:
          $ref: '#/components/schemas/UserStripeCustomer6'
        fromNotBerryForbiddenCountry:
          type: boolean
          default: false
        verified:
          type: boolean
          default: false
        emailVerified:
          type: boolean
          default: false
        phoneVerified:
          type: boolean
          default: false
        registered:
          type: boolean
          default: true
        statusType:
          type: string
          default: regular
          enum:
          - regular
          - premium
          - premium_pending
          - vip
          - vip_pending
        rentalHistory:
          type: array
          items:
            $ref: '#/components/schemas/UserRentalHistory2'
        deleted:
          type: boolean
          default: false
        locale:
          type: string
          default: en_US
          enum:
          - en_US
          - es_ES
        currency:
          type: string
        lengthUnit:
          type: string
          enum:
          - m
          - ft
      type: object
    Rental4:
      properties:
        listing:
          $ref: '#/components/schemas/Listing7'
        apartmentId:
          title: for iOs compatibility.
          type: integer
        activeSubscription:
          $ref: '#/components/schemas/RentalSubscription'
        id:
          type: integer
        application:
          $ref: '#/components/schemas/ListingApplication4'
        moveIn:
          type: string
          format: date-time
        moveOut:
          type: string
          format: date-time
        firstPaymentDate:
          type: string
          format: date-time
        monthlyRentAmount:
          type: string
          maximum: 9999999
          minimum: 1
        monthlyDueDate:
          type: integer
        tenantFirstName:
          type: string
        tenantLastName:
          type: string
        tenantEmail:
          type: string
        address:
          type: string
        unit:
          type: string
        homeowner:
          $ref: '#/components/schemas/User6'
        tenant:
          $ref: '#/components/schemas/User6'
        status:
          type: string
          default: pending
        isChargeable:
          type: boolean
          default: false
        documents:
          type: array
          items:
            $ref: '#/components/schemas/UserDocument'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    RentalType:
      required:
      - moveIn
      - moveOut
      - firstPaymentDate
      - monthlyRentAmount
      - monthlyDueDate
      - tenantFirstName
      - tenantLastName
      - tenantEmail
      - address
      - unit
      properties:
        moveIn:
          type: integer
        moveOut:
          type: integer
        firstPaymentDate:
          type: integer
        monthlyRentAmount:
          type: number
        monthlyDueDate:
          type: integer
        tenantFirstName:
          type: string
        tenantLastName:
          type: string
        tenantEmail:
          type: string
        address:
          type: string
        unit:
          type: string
      type: object
    Applicant:
      required:
      - employmentType
      properties:
        id:
          type: integer
        apartmentApply:
          $ref: '#/components/schemas/ListingApplication'
        user:
          $ref: '#/components/schemas/User'
        references:
          type: array
          items:
            $ref: '#/components/schemas/ApplicantReference'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ApplicantAttachment'
        creator:
          type: boolean
          default: false
        active:
          type: boolean
          default: false
        rentalHistory:
          type: array
          items:
            $ref: '#/components/schemas/UserRentalHistory'
        employmentType:
          type: string
          enum:
          - employed
          - unemployed
          - student
        employmentName:
          type: string
          maxLength: 255
          minLength: 1
        employmentTitle:
          type: string
          maxLength: 255
          minLength: 1
        employmentSourceIncome:
          type: string
          maxLength: 255
          minLength: 1
        employmentIncome:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    User:
      required:
      - nameFirst
      - nameLast
      - username
      - phone
      - birthday
      properties:
        hasPassword:
          type: boolean
        phoneCountryCode:
          type: string
        id:
          type: integer
        nameFirst:
          type: string
          maxLength: 255
          minLength: 2
        nameMiddle:
          type: string
          maxLength: 255
          minLength: 1
        nameLast:
          type: string
          maxLength: 255
          minLength: 2
        company:
          $ref: '#/components/schemas/Company'
        companyName:
          type: string
          maxLength: 255
          minLength: 1
        username:
          type: string
          maxLength: 255
          minLength: 1
        profilePictureThumbs:
          type: string
        phone:
          type: string
          maxLength: 15
          minLength: 7
        birthday:
          type: string
          format: date-time
        bio:
          type: string
          maxLength: 1500
        oauthProviders:
          type: array
          items:
            $ref: '#/components/schemas/UserOauthProvider'
        address:
          $ref: '#/components/schemas/UserAddress'
        creditScore:
          $ref: '#/components/schemas/UserCreditScore'
        criminalReport:
          $ref: '#/components/schemas/UserCriminalReport'
        stripeCustomer:
          $ref: '#/components/schemas/UserStripeCustomer'
        active:
          type: boolean
          default: true
        fromNotBerryForbiddenCountry:
          type: boolean
          default: false
        verified:
          type: boolean
          default: false
        emailVerified:
          type: boolean
          default: false
        phoneVerified:
          type: boolean
          default: false
        registered:
          type: boolean
          default: true
        emailNotVerifiedAfter:
          type: string
          format: date-time
        lastActiveAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        statusType:
          type: string
          default: regular
          enum:
          - regular
          - premium
          - premium_pending
          - vip
          - vip_pending
        authToken:
          type: string
        rentalHistory:
          type: array
          items:
            $ref: '#/components/schemas/UserRentalHistory'
        deleted:
          type: boolean
          default: false
        rentalPaymentAccount:
          $ref: '#/components/schemas/RentalPaymentAccount'
        newsletterSubscription:
          type: boolean
          default: false
        premiumPartner:
          type: boolean
          default: false
        locale:
          type: string
          default: en_US
          enum:
          - en_US
          - es_ES
        currency:
          type: string
        lengthUnit:
          type: string
          enum:
          - m
          - ft
        isRaiUser:
          type: boolean
          default: false
      type: object
    UserDocument:
      required:
      - name
      properties:
        id:
          type: integer
        name:
          type: string
        mimeType:
          type: string
        size:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    UserRentalHistory:
      required:
      - address
      - city
      - homeownerPhone
      properties:
        id:
          type: integer
        user:
          $ref: '#/components/schemas/User'
        applicantId:
          type: integer
        address:
          type: string
          maxLength: 255
          minLength: 3
        city:
          type: string
          maxLength: 255
          minLength: 3
        price:
          type: integer
        term:
          type: integer
        homeownerPhone:
          type: integer
          maxLength: 15
          minLength: 7
      type: object
    ApplicantReference:
      required:
      - name
      - relationship
      - phone
      properties:
        id:
          type: integer
        applicant:
          $ref: '#/components/schemas/Applicant'
        name:
          type: string
          maxLength: 255
          minLength: 1
        relationship:
          type: string
          maxLength: 255
          minLength: 1
        email:
          type: string
        phone:
          type: integer
          maxLength: 15
          minLength: 7
      type: object
    RentalPaymentAccount:
      properties:
        stripeAccountId:
          type: string
        isStripeOnboardingFinished:
          type: boolean
          default: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    Coordinates:
      properties:
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
      type: object
    InviteHomeownerType:
      required:
      - email
      properties:
        email:
          type: string
      type: object
    UserAddress:
      required:
      - street
      - houseNumber
      - city
      - zip
      properties:
        street:
          type: string
          maxLength: 255
          minLength: 1
        houseNumber:
          type: string
          maxLength: 255
          minLength: 1
        streetType:
          type:
          - string
          - 'null'
          maxLength: 10
        city:
          type: string
          maxLength: 255
          minLength: 3
        state:
          $ref: '#/components/schemas/State'
        zip:
          type: string
          maxLength: 9
          minLength: 5
      type: object
    UserCriminalReport:
      properties:
        criminalRecordFound:
          type: boolean
          default: false
        status:
          type: integer
          maxLength: 10
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    UserStripeCustomer:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    State:
      properties:
        id:
          type: integer
        shortName:
          type:
          - string
          - 'null'
          default: null
          maxLength: 200
          minLength: 1
        name:
          type:
          - string
          - 'null'
          default: null
          maxLength: 255
          minLength: 1
        description:
          type: string
      type: object
    UserOauthProvider:
      properties:
        id:
          type: integer
        provider:
          type: string
        providerId:
          type: string
        connectId:
          type: string
        nameFirst:
          type: string
        nameLast:
          type: string
        pictureUrl:
          type: string
        appId:
          type: string
      type: object
    StripePayment:
      properties:
        id:
          type: integer
        amount:
          type: string
          default: '0'
        status:
          type: string
        cancellationReason:
          type: string
        errorMessage:
          type: string
        internalType:
          type: string
        last4Digits:
          type: string
        paymentMethod:
          type: string
          default: card
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    RentalSubscription:
      properties:
        id:
          type: integer
        amount:
          type: string
          default: '0'
        commissionFee:
          type: string
          default: '0'
        amountTotal:
          type: string
          default: '0'
        currency:
          type: string
        comment:
          type: string
        status:
          type: string
          default: incomplete
        paymentMethod:
          type: string
          default: card
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    Rental:
      properties:
        listing:
          $ref: '#/components/schemas/Listing'
        apartmentId:
          title: for iOs compatibility.
          type: integer
        latestPayment:
          $ref: '#/components/schemas/RentalPayment'
        activeSubscription:
          $ref: '#/components/schemas/RentalSubscription'
        id:
          type: integer
        application:
          $ref: '#/components/schemas/ListingApplication'
        moveIn:
          type: string
          format: date-time
        moveOut:
          type: string
          format: date-time
        firstPaymentDate:
          type: string
          format: date-time
        monthlyRentAmount:
          type: string
          maximum: 9999999
          minimum: 1
        monthlyDueDate:
          type: integer
        tenantFirstName:
          type: string
        tenantLastName:
          type: string
        tenantEmail:
          type: string
        address:
          type: string
        unit:
          type: string
        homeowner:
          $ref: '#/components/schemas/User'
        tenant:
          $ref: '#/components/schemas/User'
        status:
          type: string
          default: pending
        isChargeable:
          type: boolean
          default: false
        documents:
          type: array
          items:
            $ref: '#/components/schemas/UserDocument'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    AdminLevelCollection:
      properties: []
      type: object
    State2:
      properties:
        id:
          type: integer
        shortName:
          type:
          - string
          - 'null'
          default: null
          maxLength: 200
          minLength: 1
        name:
          type:
          - string
          - 'null'
          default: null
          maxLength: 255
          minLength: 1
      type: object
    Company:
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 255
          minLength: 1
        phone:
          type: integer
          maxLength: 15
          minLength: 7
        website:
          type: string
          maxLength: 255
          minLength: 1
        logoThumbs:
          type: string
        email:
          type: string
          maxLength: 255
          minLength: 1
        city:
          type: string
          maxLength: 2

# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/openapi/rentberry-rental-api-openapi.yml