Rentberry

Rentberry Screening API

Screening

GitHub OpenAPI

Documentation

📖
APIReference
https://api.rentberry.com/docs
📖
Documentation
https://api.rentberry.com/docs
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/authentication/rentberry-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/openapi/rentberry-screening-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/conventions/rentberry-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/errors/rentberry-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/data-model/rentberry-data-model.yml
🔗
Lifecycle
https://raw.githubusercontent.com/api-evangelist/rentberry/refs/heads/main/lifecycle/rentberry-lifecycle.yml

OpenAPI Specification

rentberry-screening-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Rentberry Screening API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Screening
  description: Screening
paths:
  /v{version}/screening:
    get:
      tags:
      - Screening
      summary: Get homeowner screening requests
      description: Available since API version 1. Returns paginated list of screening requests created by the authenticated homeowner.
      operationId: get_api_v1_screening_request_list
      parameters:
      - name: active
        in: query
        description: Filter by active status
        schema:
          type: boolean
          default: true
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        description: Items per page
        schema:
          type: integer
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of screening requests with notifications
          content:
            application/json:
              schema:
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScreeningResponse'
                  pagination:
                    description: Pagination information
                    type: object
                type: object
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
    post:
      tags:
      - Screening
      summary: Create screening requests
      description: Available since API version 1. Creates screening requests for one or more tenants and sends email invitations.
      operationId: post_api_v1_screening_request_create
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreeningRequestsType'
      responses:
        '200':
          description: Screening requests created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScreeningResponse'
        '400':
          description: Validation failed
        '401':
          description: Unauthorized
      security:
      - XAuthToken: []
  /v{version}/screening/{reference}:
    get:
      tags:
      - Screening
      summary: Get screening request by reference
      description: Available since API version 1. Returns screening request details using reference code from email invitation.
      operationId: get_api_v1_screening_request_get
      parameters:
      - name: reference
        in: path
        description: Unique reference code
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Screening request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRequest'
        '404':
          description: Screening request not found
  /v{version}/screening/resend/{id}:
    post:
      tags:
      - Screening
      summary: Resend screening request email
      description: Available since API version 1. Resends email invitation to tenant for an existing screening request.
      operationId: post_api_v1_screening_request_resend
      parameters:
      - name: id
        in: path
        description: Screening request ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Email resent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningResponse'
        '401':
          description: Unauthorized
        '403':
          description: Not your screening request
        '404':
          description: (Real code 11001) Request already deleted
        '405':
          description: (Real code 11002) Request already canceled
        '406':
          description: (Real code 11009) Request already completed
      security:
      - XAuthToken: []
  /v{version}/screening/{id}:
    delete:
      tags:
      - Screening
      summary: Cancel screening request
      description: Available since API version 1. Cancels an active screening request. Cannot cancel completed or paid requests.
      operationId: delete_api_v1_screening_request_cancel
      parameters:
      - name: id
        in: path
        description: Screening request ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Request canceled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreeningRequest2'
        '401':
          description: Unauthorized
        '403':
          description: Not your screening request
        '404':
          description: (Real code 11001) Request already deleted
        '405':
          description: (Real code 11002) Request already canceled
        '406':
          description: (Real code 11006) Cannot cancel completed screening
        '407':
          description: (Real code 11011) Cannot cancel paid screening
      security:
      - XAuthToken: []
  /v{version}/screening/screen/{reference}/pay:
    post:
      tags:
      - Screening
      summary: Pay for screening (deprecated)
      description: 'Available since API version 1. DEPRECATED: Use Stripe webhook instead. Associates feature ticket with screening request.'
      operationId: post_api_v1_screening_screen_pay
      parameters:
      - name: reference
        in: path
        description: Screening reference code
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        content:
          application/json:
            schema:
              properties:
                ticket:
                  description: Feature ticket code
                  type: string
              type: object
      responses:
        '200':
          description: Payment processed
        '402':
          description: Payment required or invalid ticket
      deprecated: true
  /v{version}/screening/validate/{reference}:
    post:
      tags:
      - Screening
      summary: Validate tenant data for screening
      description: Available since API version 1. Validates tenant personal information before performing actual screening.
      operationId: post_api_v1_screening_validate_screening_data
      parameters:
      - name: reference
        in: path
        description: Screening reference code
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreditScoreCheckType'
      responses:
        '200':
          description: Data validated successfully
        '400':
          description: Validation failed
        '402':
          description: Payment required
        '404':
          description: (Real code 11001) Request already deleted
        '405':
          description: (Real code 11004) Request already processed
  /v{version}/screening/screen/{reference}:
    post:
      tags:
      - Screening
      summary: Perform tenant screening
      description: Available since API version 1. Executes credit and criminal background screening for tenant using validated data.
      operationId: post_api_v1_screening_screen_user
      parameters:
      - name: reference
        in: path
        description: Screening reference code
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreditScoreCheckType'
      responses:
        '200':
          description: Screening completed successfully
        '400':
          description: Validation failed
        '402':
          description: Payment required
        '404':
          description: (Real code 11007) Request was canceled
        '405':
          description: (Real code 11004) Request already processed
        '406':
          description: (Real code 11005) Error obtaining screening reports
components:
  schemas:
    ScreeningRequestCreateType:
      required:
      - tenantNameFirst
      - tenantNameLast
      - tenantEmail
      properties:
        tenantNameFirst:
          type: string
        tenantNameLast:
          type: string
        tenantEmail:
          type: string
      type: object
    User7:
      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/UserStripeCustomer7'
        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
        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
    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
    ScreeningRequest2:
      properties:
        id:
          type: integer
        homeowner:
          $ref: '#/components/schemas/User'
        status:
          type: integer
          default: 1
        active:
          type: boolean
          default: true
        deleted:
          type: boolean
          default: false
        tenantEmail:
          type: string
        tenantNameFirst:
          type: string
        tenantNameLast:
          type: string
        reference:
          type: string
        creditScore:
          $ref: '#/components/schemas/UserCreditScore'
        criminalReport:
          $ref: '#/components/schemas/UserCriminalReport'
        expiredAt:
          type: string
          format: date-time
        featureTicket:
          $ref: '#/components/schemas/FeatureTicket'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    AccountCreditScoreCheckType:
      required:
      - nameFirst
      - nameMiddle
      - nameLast
      - phone
      - birthday
      - address
      - creditScore
      - pinCode
      properties:
        nameFirst:
          type: string
        nameMiddle:
          type: string
        nameLast:
          type: string
        phone:
          type: integer
        birthday:
          type: integer
        address:
          $ref: '#/components/schemas/AccountAddressType'
        creditScore:
          $ref: '#/components/schemas/AccountCreditScoreType'
        pinCode:
          type: string
      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
    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
    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
    ScreeningRequestsType:
      required:
      - users
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/ScreeningRequestCreateType'
      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
    FeatureTicket:
      properties:
        id:
          type: integer
        code:
          type: string
        type:
          type: string
        usedAt:
          type: string
          format: date-time
        isUsed:
          type: boolean
          default: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    ScreeningRequest:
      properties:
        id:
          type: integer
        homeowner:
          $ref: '#/components/schemas/User7'
        status:
          type: integer
          default: 1
        active:
          type: boolean
          default: true
        deleted:
          type: boolean
          default: false
        tenantEmail:
          type: string
        tenantNameFirst:
          type: string
        tenantNameLast:
          type: string
        reference:
          type: string
        creditScore:
          $ref: '#/components/schemas/UserCreditScore'
        criminalReport:
          $ref: '#/components/schemas/UserCriminalReport'
        expiredAt:
          type: string
          format: date-time
        featureTicket:
          $ref: '#/components/schemas/FeatureTicket'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    AccountAddressType:
      required:
      - street
      - houseNumber
      - city
      - zip
      - stateId
      properties:
        street:
          type: string
        houseNumber:
          type: string
        streetType:
          type: string
        city:
          type: string
        zip:
          type: string
        stateId:
          type: integer
      type: object
    ScreeningResponse:
      properties: []
      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
    UserStripeCustomer7:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User7'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    AccountCreditScoreType:
      required:
      - ssn
      properties:
        ssn:
          type: string
      type: object