Rentberry Rentals API

openapi: 3.2.0
info:
  title: Rentberry Rentals API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Rentals
  description: Rentals
paths:
  /v{version}/rental/{rental_id}/payment/stripe:
    get:
      tags:
      - Rentals
      summary: List payments for rental
      description: Available since API version 1. Returns paginated list of Stripe payments for a specific rental with notification status.
      operationId: get_api_v1_rental_payment_list_for_rental_stripe
      parameters:
      - name: rental_id
        in: path
        description: Rental ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of rental payments
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RentalPaymentResponseItem'
                  pagination:
                    type: object
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to view this rental
      security:
      - XAuthToken: []
    post:
      tags:
      - Rentals
      summary: Create Stripe payment
      description: Available since API version 1. Creates a Stripe payment for a rental and returns clientSecret for frontend payment form.
      operationId: post_api_v1_rental_payment_stripe
      parameters:
      - name: rental_id
        in: path
        description: Rental ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - amount
              properties:
                amount:
                  description: Payment amount
                  type: number
                  format: float
                description:
                  description: Payment description
                  type: string
              type: object
      responses:
        '200':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StripePaymentCreatedResponse'
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to view this rental
      security:
      - XAuthToken: []
  /v{version}/rental/payment/{rental_payment_id}/stripe/update:
    post:
      tags:
      - Rentals
      summary: Update Stripe payment
      description: Available since API version 1. Updates an existing Stripe payment.
      operationId: post_api_v1_rental_payment_stripe_update
      parameters:
      - name: rental_payment_id
        in: path
        description: Rental payment ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Updated payment amount
                  type: number
                  format: float
                description:
                  description: Updated payment description
                  type: string
              type: object
      responses:
        '200':
          description: Payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StripePaymentCreatedResponse'
        '400':
          description: Bad request - Validation failed
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to update this payment
      security:
      - XAuthToken: []
  /v{version}/rental/payment/{rental_payment_id}/stripe:
    delete:
      tags:
      - Rentals
      summary: Cancel Stripe payment
      description: Available since API version 1. Cancels an existing Stripe payment.
      operationId: delete_api_v1_rental_payment_stripe_cancel
      parameters:
      - name: rental_payment_id
        in: path
        description: Rental payment ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Payment cancelled successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to cancel this payment
      security:
      - XAuthToken: []
components:
  schemas:
    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
    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
    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
    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
    Coordinates:
      properties:
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
      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
    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
    UserStripeCustomer:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      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
    NotificationsState:
      properties:
        readed:
          type: boolean
        viewed:
          type: boolean
      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
    ListingPicture:
      required:
      - id
      properties:
        id:
          type: integer
        imageThumbs:
          type: string
        order:
          type: integer
        type:
          type: string
          default: picture
      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: 255
          minLength: 1
        countryCode:
          type: string
          maxLength: 2
          minLength: 2
        provider:
          type: string
        externalId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    Listing:
      required:
      - name
      - type
      - description
      - externalKey
      properties:
        openHousesEnabled:
          type: boolean
        leadUrl:
          type: boolean
        price:
          type: number
          format: float
        priceTerm:
          type: string
        user:
          $ref: '#/components/schemas/User'
        active:
          type: boolean
        rented:
          type: boolean
        providerType:
          type: string
        editedByUser:
          title: legacy.
          type: boolean
        expired:
          type: boolean
        promoted:
          type: boolean
        currency:
          type: string
        company:
          $ref: '#/components/schemas/Company'
        expireAt:
          type: integer
        listingStatus:
          type: string
        hasVirtualTour:
          type: boolean
        originalPrice:
          $ref: '#/components/schemas/Price'
        rooms:
          title: legacy.
          type: integer
        traffic:
          title: legacy.
          type: integer
        rentDuration:
          title: legacy.
          type: integer
        unitNumber:
          title: legacy.
          type: string
        levelId:
          title: legacy.
          type: integer
        shapeId:
          title: legacy.
          type: string
        panoramaId:
          title: legacy.
          type: string
        occupant:
          title: legacy.
          type: string
        id:
          type: integer
        apartmentPictures:
          type: array
          items:
            $ref: '#/components/schemas/ListingPicture'
        virtualTours:
          type: array
          items:
            $ref: '#/components/schemas/VirtualTour'
        address:
          $ref: '#/components/schemas/ListingAddress'
        apartmentApplies:
          type: array
          items:
            $ref: '#/components/schemas/ListingApplication'
        openHouseApplications:
          type: array
          items:
            $ref: '#/components/schemas/OpenHouseApplication'
        name:
          type: string
          maxLength: 255
          minLength: 1
        available:
          type: string
          format: date-time
        space:
          type: integer
          maximum: 99999
        lengthUnit:
          type: string
          enum:
          - ft
          - m
        type:
          type: string
          enum:
          - apartment
          - house
          - condo
          - townhouse
          - duplex
          - loft
          - room
          - land
          - other
        deposit:
          type: integer
          maximum: 999999999
          minimum: 0
        utilitiesPrice:
          type: integer
          maximum: 999999999
          minimum: 0
        description:
          type: string
          maxLength: 10000
        isAIDescription:
          type: boolean
          default: false
        deleted:
          type: boolean
          default: false
        syndicated:
          type: boolean
          default: false
        externalUrl:
          type: string
          maxLength: 2048
        seoUrl:
          type: string
        externalKey:
          type: string
        listedAt:
          type: string
          format: date-time
        publishedAt:
          title: Date when listing was published on MLS.
          type: string
          format: date-time
        provider:
          type: string
          default: rentberry
          enum:
          - rentberry
          - apartmentlist
          - apts
          - avail
          - bondnewyork
          - bostonapartments
          - collegestudentapartments
          - commercialpropertykenya
          - eurovilla
          - expedia
          - findroommate
          - flatio
          - fourstay
          - foreclosure
          - fultongrace
          - goplaceit
          - harlington
          - hemavi
          - homestay
          - housinganywhere
          - housestay
          - huurstunt
          - inlife
          - joivy
          - junehome
          - krn
          - levit
          - livinfrance
          - mapaprop
          - morningcroissant
          - mystate
          - navent
          - onthemarket
          - openimmo
          - padfinders
          - padsplit
          - parisattitude
          - pepehousing
          - pin
          - realbird
          - reallyo
          - realtymx
          - realtyww
          - rentalsource
          - rentengine
          - renthia
          - rentinsingapore
          - rentola
          - roomless
          - roomster
          - samtrygg
          - siamrealestate
          - speedhome
          - spotahome
          - 3dapartment
          - turbotenant
          - uniplaces
          - wunderflats
          - yourrentals
          - yucalive
          - xml2u
          - ziptoss
          - cheznestor
          - coliving
          - domaingroup
          - erasmusu
          - explorastay
          - rentcatalogue
          - homelike
          - hyrenbostad
          - lejebolig
          - listhub
          - properstar
          - studentsglobalrelocation
          - zappyrent
          - zeusliving
        maintenance:
          type: array
          items:
            $ref: '#/components/schemas/Maintenance'
        amenities:
          type: array
          items:
            enum:
            - gym
            - pool
            - garden
            - parking
            - doorman
            - storage
            - balcony
            - elevator
            - fireplace
            - highRise
            - roofDeck
            - furnished
            - dishwasher
            - beachView
            - washerUnit
            - hardwoodFloors
            - airConditioning
            - wheelchairAccessible
            - attic
            - basement
            - bbqArea
            - deck
            - disabledAccess
            - garageParking
            - greenhouse
            - intercom
            - lawn
            - new
            - secondarySuite
            - security
            - waterfront
            - wired
            - newConstruction
            - securitySystem
            - hotTube
            - studentFriendly
            - utilitiesIncluded
            - energyEfficient
            - solarPowered
            - kitchen
            - privateKitchen
            - sharedKitchen
            - internet
            - wifi
            - tv
            - localTv
            - cableTv
            - computer
            - laptopWorkspace
            - hotTube
            - tub
            - iron
            - towels
            - ironingBoard
            - toiletries
            - guestToilet
            - buzzerWirelessIntercom
            - privateEntrance
            - hairDryer
            - suitableForEvents
            - centralizedHeating
            - autonomousHeating
            - busStop
            - trainStation
            - airport
            - bicyclesForUse
            - library
            - shoppingCenter
            - hospital
            - park
            - golf
            - museums
            - healthClub
            - amusementPark
            - cinema
            - restaurant
            - gamesRoom
            - horseStables
            - bowling
            - smokeAlarm
            - smokeAlarmEachFloor
            - sportsArena
            - coDetector
            - cellar
            - blankets
            - pillows
            - bedClothes
            - broom
            - floorWiper
            - shower
            - toaster
            - microwave
            - fridge
            - coffee
            - kettle
            - cutlery
            - vacuumCleaner
            - stove
            - detergents
            - bidet
            - hourSecurity24
            - fishing
            - waterSports
            - creditApplication
            - smokingFriendly
            - brokerFee
            - garbageDisposer
            - iceMaker
            - trashCompactor
            - warmingDrawer
            - coffeeSystem
            - coffeeSystemRoughIn
            - cooktop
            - cooktopElectric
            - cooktopElectric2Burner
            - cooktopElectric6Burner
            - cooktopGas
            - cooktopGas2Burner
            - cooktopGas5Burner
            - cooktopGas6Burner
            - cooktopGasCustom
            - cooktopInduction
            - cooktopInduction2Burner
            - cooktopInduction6Burner
            - dishwasherDrawer
            - dishwasherTwoOrMore
            - dryer
            - dryerDualFuel
            - dryerElectric110v
            - dryerElectric220v
            - dryerGas
            - dryerGasRoughIn
            - oven
            - ovenConvection
            - ovenDouble
            - ovenDoubleElectric
            - ovenDoubleGas
            - ovenGas
            - ovenGas3Wide
            - ovenSelfCleaning
            - ovenSteam
            - ovenTwin
            - ovenTwinElectric
            - ovenTwinGas
            - ovenTwinGas3Wide
            - ovenTwinMixed
            - range
            - rangeBuiltIn
            - rangeDual
            - rangeDual10Burner
            - rangeDual6Burner
            - rangeDual8Burner
            - rangeElectric
            - rangeGas
            - rangeGas10Burner
            - rangeGas6Burner
            - rangeGas8Burner
            - rangeInduction
            - rangeOther
            - rangetopElectric
            - rangetopElectric2Burner
            - rangetopElectric6Burner
            - rangetopGas
            - rangetopGas10Burner
            - rangetopGas2Burner
            - rangetopGas4BurnerCompact
            - rangetopGas6Burner
            - rangetopGas8Burner
            - rangetopGasCustom
            - rangetopInduction
            - rangetopInduction2Burner
            - rangetopInduction6Burner
            - freezer
            - freezerCompact
            - freezerUpright
            - refrigerator
            - refrigeratorBar
            - refrigeratorBuiltIn
            - refrigeratorBuiltInWithPlumbing
            - refrigeratorDrawer
            - refrigeratorSideBySide
            - refrigeratorUndercounter
            - refrigeratorWineStorage
            - refrigeratorWithPlumbing
            - vacuumSystem
            - vacuumSystemRoughIn
            - ventHood
            - ventHood10Burner
            - ventHood6Burner
            - ventHood8Burner
            - washer
            - washerFrontLoad
            - washerSteamer
            - washerTopLoad
            - washerDryerCombo
            - washerDryerStack
            - waterFilter
            - waterInstantHot
            - waterPurifier
            - waterSoftener
            - architectureAFrame
            - architectureArtDeco
            - architectureBungalow
            - architectureCapeCod
            - architectureColonial
            - architectureContemporary
            - architectureConventional
            - architectureCottage
            - architectureCraftsman
            - architectureCreole
            - architectureDome
            - architectureDutchColonial
            - architectureEnglish
            - architectureFederal
            - architectureFrench
            - architectureFrenchProvincial
            - architectureGeorgian
            - architectureGothicRevival
            - architectureGreekRevival
            - architectureHighRise
            - architectureHistorical
            - architectureInternational
            - architectureItalianate
            - architectureLoft
            - architectureMansion
            - architectureMediterranean
            - architectureModern
            - architectureMonterey
            - architectureMountain
            - architectureNational
            - architectureNeoclassical
            - architectureNewTraditional
            - architecturePrairie
            - architecturePueblo
            - architectureQueenAnne
            - architectureRambler
            - architectureRanch
            - architectureRegency
            - architectureRustic
            - architectureSaltbox
            - architectureSantaFe
            - architectureSecondEmpire
            - architectureShed
            - architectureShingle
            - architectureShotgun
            - architectureSpanish
            - architectureSpanishEclectic
            - architectureSplitLevel
            - architectureStick
            - architectureTudor
            - architectureVictorian
            - coolingAtticFan
            - coolingCeilingFan
            - coolingCentralAC
            - coolingCentralEvaporative
            - coolingCentralFan
            - coolingChilledWater
            - coolingDehumidifiers
            - coolingDessicantCooler
            - coolingEvaporative
            - coolingHeatPumps
            - coolingPartial
            - coolingRadiantFloor
            - coolingRadiantFloorGroundLoop
            - coolingRefrigeratorEvaporative
            - coolingSolarAcActive
            - coolingSolarAcPassive
            - coolingWallUnitAc
            - coolingWallUnitEvaporative
            - coolingWindowUnitAc
       

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