Rentberry Contracts API

openapi: 3.2.0
info:
  title: Rentberry Contracts API
  description: Renting Done Right. Finally.
  version: 4
tags:
- name: Contracts
  description: Contracts
paths:
  /v{version}/contract:
    get:
      tags:
      - Contracts
      summary: List signed contracts
      description: Available since API version 1. Returns a list of signed contracts for the authenticated user.
      operationId: get_api_v1_contract_list
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: List of signed contracts
          content:
            application/json:
              schema:
                properties:
                  items:
                    description: List of contracts
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
      security:
      - XAuthToken: []
    post:
      tags:
      - Contracts
      summary: Create a new contract
      description: Available since API version 1. Creates a new contract based on a template and associates it with a rental.
      operationId: post_api_v1_contract_create
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - contractTemplateId
              - rentalId
              properties:
                contractTemplateId:
                  description: ID of the contract template to use
                  type: integer
                rentalId:
                  description: ID of the rental to associate with the contract
                  type: integer
                signerEmail:
                  description: Email of the signer (optional)
                  type: string
                  format: email
                signerName:
                  description: Name of the signer (optional)
                  type: string
              type: object
      responses:
        '200':
          description: Contract created successfully
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: Contract ID
                    type: integer
                  url:
                    description: URL for editing the contract
                    type: string
                type: object
        '400':
          description: Bad request - validation failed
        '402':
          description: Payment required - Feature is locked
        '404':
          description: Contract template or rental not found
        '405':
          description: (Real code 6018) Template is not owned by current user
        '406':
          description: (Real code 6023) Cannot create contract for someone else's apartment
        '407':
          description: (Real code 6025) Template error - cannot resolve contract template file
      security:
      - XAuthToken: []
  /v{version}/contract/publish/{id}:
    post:
      tags:
      - Contracts
      summary: Publish contract
      description: Available since API version 1. Initiates the contract publishing process and returns signing URL if embedded signing is required.
      operationId: post_api_v1_contract_publish
      parameters:
      - name: id
        in: path
        description: Contract ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract published successfully or signing URL returned
          content:
            application/json:
              schema:
                properties:
                  url:
                    description: URL for embedded signing (if applicable)
                    type: string
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '400':
          description: Error - Signature not found or unable to generate signing URL
      security:
      - XAuthToken: []
  /v{version}/contract/invite/{id}:
    post:
      tags:
      - Contracts
      summary: Invite to sign contract
      description: Available since API version 1. Sends an invitation email to the homeowner to sign a contract.
      operationId: post_api_v1_contract_invite
      parameters:
      - name: 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: Invitation sent successfully
          content:
            application/json:
              schema:
                properties: []
                type: object
              example: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '404':
          description: Rental not found
        '500':
          description: Error sending email
      security:
      - XAuthToken: []
  /v{version}/contract/rental/{id}:
    get:
      tags:
      - Contracts
      summary: List contracts for a rental
      description: Available since API version 1. Returns a list of contracts associated with a specific rental.
      operationId: get_api_v1_contract_rental_list
      parameters:
      - name: 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 contracts for the rental
          content:
            application/json:
              schema:
                properties:
                  items:
                    description: List of contracts with notification counts
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract2'
                type: object
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to view this rental
        '404':
          description: Rental not found
      security:
      - XAuthToken: []
  /v{version}/contract/sign/{id}:
    get:
      tags:
      - Contracts
      summary: Get contract signing URL
      description: Available since API version 1. Returns a URL for signing a contract using embedded signing.
      operationId: get_api_v1_contract_sign
      parameters:
      - name: id
        in: path
        description: Contract ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract signing URL returned
          content:
            application/json:
              schema:
                properties:
                  url:
                    description: URL for embedded signing
                    type: string
                type: object
        '403':
          description: Forbidden - User does not have permission to view this rental
        '404':
          description: Contract not found
        '405':
          description: (Real code 6024) Contract already signed
        '400':
          description: Error getting signing URL
  /v{version}/contract/sign/token/{token}:
    get:
      tags:
      - Contracts
      summary: Sign contract with token
      description: Available since API version 1. Returns a URL for signing a contract using a sign token.
      operationId: get_api_v1_contract_sign_by_token
      parameters:
      - name: token
        in: path
        description: Contract sign token
        required: true
        schema:
          type: string
          pattern: ^\w+$
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract signing URL returned
          content:
            application/json:
              schema:
                properties:
                  url:
                    description: URL for embedded signing
                    type: string
                type: object
        '404':
          description: Token not found
        '405':
          description: (Real code 6024) Contract already signed
        '400':
          description: Error getting signing URL
  /v{version}/contract/{id}/signatures:
    get:
      tags:
      - Contracts
      summary: Get contract signatures
      description: Available since API version 1. Returns information about signatures for a specific contract.
      operationId: get_api_v1_contract_signatures
      parameters:
      - name: id
        in: path
        description: Contract ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract signatures information
          content:
            application/json:
              schema:
                description: List of contract signatures
                type: array
                items:
                  $ref: '#/components/schemas/ContractSignature2'
        '403':
          description: Forbidden - User does not have permission to view this contract
        '404':
          description: Contract not found
  /v{version}/contract/{id}:
    delete:
      tags:
      - Contracts
      summary: Delete contract
      description: Available since API version 1. Deletes a contract. Only the homeowner of the associated listing can delete the contract.
      operationId: delete_api_v1_contract_delete
      parameters:
      - name: id
        in: path
        description: Contract ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract deleted 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 delete this contract
        '404':
          description: Contract not found
      security:
      - XAuthToken: []
  /v{version}/contract/download/{id}:
    get:
      tags:
      - Contracts
      summary: Download contract
      description: Available since API version 1. Downloads the signed contract as a PDF file.
      operationId: get_api_v1_contract_download
      parameters:
      - name: id
        in: path
        description: Contract ID
        required: true
        schema:
          type: integer
          pattern: \d+
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      responses:
        '200':
          description: Contract PDF file
          headers:
            Content-Disposition:
              description: Attachment filename
              schema:
                type: string
          content:
            application/pdf: []
        '401':
          description: Unauthorized - Missing or invalid authentication token
        '403':
          description: Forbidden - User does not have permission to download this contract
        '400':
          description: Error downloading contract file
      security:
      - XAuthToken: []
  /v{version}/contract/callback:
    post:
      tags:
      - Contracts
      summary: Handle contract signing callback
      description: Available since API version 1. Processes callbacks from Dropbox Sign when contracts are signed or declined.
      operationId: post_api_v1_contract_callback
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: string
          pattern: \d+
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                json:
                  description: JSON payload from Dropbox Sign containing event data
                  type: string
                  example: '{"event":{"event_type":"signature_request_signed","event_metadata":{"related_signature_id":"abc123"}}}'
              type: object
      responses:
        '200':
          description: Callback processed successfully
          content:
            application/json:
              schema:
                type: string
              example: Hello API Event Received
        '400':
          description: Bad request - Invalid callback payload
          content:
            application/json:
              schema:
                type: string
              example: No signature provided
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
    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
    Applicant2:
      properties:
        id:
          type: integer
        user:
          $ref: '#/components/schemas/User3'
        creator:
          type: boolean
          default: false
        active:
          type: boolean
          default: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
    ContractSignature2:
      properties:
        isOwner:
          type: boolean
          default: false
        id:
          type: integer
        status:
          type: integer
        providerId:
          type: string
        signerEmail:
          type: string
        signerName:
          type: string
        user:
          $ref: '#/components/schemas/User'
        userId:
          type: integer
        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
    Contract:
      properties:
        isEmail:
          title: Indicates that process of signing must be done via email (not HelloSign embedded way).
          type: boolean
        contractSignatures:
          type: array
          items:
            $ref: '#/components/schemas/ContractSignature'
        user:
          $ref: '#/components/schemas/User3'
        id:
          type: integer
        providerId:
          type: string
        name:
          type: string
        signerName:
          type: string
        signerEmail:
          type: string
        providerTemplateId:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
        createdBy:
          type: integer
        rental:
          $ref: '#/components/schemas/Rental2'
        userNotificationsCount:
          type: integer
          default: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      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
    Contract2:
      properties:
        isEmail:
          title: Indicates that process of signing must be done via email (not HelloSign embedded way).
          type: boolean
        contractSignatures:
          type: array
          items:
            $ref: '#/components/schemas/ContractSignature2'
        user:
          $ref: '#/components/schemas/User'
        id:
          type: integer
        providerId:
          type: string
        name:
          type: string
        signerName:
          type: string
        signerEmail:
          type: string
        providerTemplateId:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
        createdBy:
          type: integer
        rental:
          $ref: '#/components/schemas/Rental'
        userNotificationsCount:
          type: integer
          default: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      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
    ContractSignature:
      properties:
        isOwner:
          type: boolean
          default: false
        id:
          type: integer
        status:
          type: integer
        providerId:
          type: string
        signerEmail:
          type: string
        signerName:
          type: string
        user:
          $ref: '#/components/schemas/User3'
        userId:
          type: integer
        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
    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
    ListingApplication2:
      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
        price:
          type: string
          minimum: 1
        term:
          type: integer
        moveIn:
          type: string
          format: date-time
        applicants:
          type: array
          items:
            $ref: '#/components/schemas/Applicant2'
        declinedReason:
          type: string
          maxLength: 255
          minLength: 1
        new:
          type: boolean
          default: true
        showNotification:
          type: boolean
          default: false
        status:
          type: string
          default: draft
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      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
    UserStripeCustomer3:
      properties:
        customerId:
          type: string
        user:
          $ref: '#/components/schemas/User3'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      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
    Rental2:
      properties:
        listing:
          $ref: '#/components/schemas/Listing2'
        apartmentId:
          title: for iOs compatibility.
          type: integer
        activeSubscription:
          $ref: '#/components/schemas/RentalSubscription'
        id:
          type: integer
        application:
          $ref: '#/components/schemas/ListingApplication2'
        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/User3'
        tenant:
          $ref: '#/components/schemas/User3'
        status:
          type: string
          default: pending
        isChargeable:
          t

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