Guides
Start typing to search…

Updating HOA User Data

Learn how to build the /portal_info request payload for HOA users

ℹ️ Overview

This guide explains how to build the /portal_info request body for HOA users.

  • We’ll walk through each request field and explain how to populate it for HOA users.
  • Then we’ll build a full payload step by step to show how it all fits together.

📌 Before we begin

📘

This section focuses on fields that are populated differently for HOA users versus flexible rent users It does not cover how to build the /portal_info request payload from scratch.

If you’re not already familiar with it, review the 📖 Updating Tenant Data guide before continuing.

⚠️

As outlined in the 📖 Flexible HOA Payments (Optional) guide,
flexible HOA payments are supported only for HOA users with a monthly billing frequency.

/portal_info requests are expected only for these users.

If an HOA user is billed at a different frequency, do not send a /portal_info request for them.

❓Why is this guide needed?

The 📖 Updating Tenant Data section already explains in detail how to create /portal_info requests.

So why is a separate guide for HOA users needed?

The Livble API is primarily designed for flexible rent flows.
As a result, constructing /portal_info requests for HOA users can be unintuitive.

This guide will clarify exactly how the request should be created for HOA users with a two-step approach:

  • First, review the request field-by-field and explains whether it remains unchanged, should be omitted, or requires HOA-specific handling.
  • Then, it walks through a complete /portal_info request example step by step to show how everything fits together.

📋 Field reference

This section provides a complete, field-by-field reference for the /portal_info request, with HOA-specific guidance where applicable.

1️⃣ Root Object

The table below documents all root-level fields in the /portal_info request body,
and explains how to populate them for HOA users.

🏷️ Field ⚙️ How to populate
name (required) The user's first name.
surname (required) The user's last name.
phone_number The user's phone number.
email (required) The user's email address.
refresh_date The date the information was last updated.
If not provided, it defaults to the current time.
product_variant Specifies the product variant for the user: "hoa" | "rent"
If the field is not provided, it defaults to "rent"

❗Consistency is enforced across requests
Once a /portal_info/:id request is made for an ID,
the product_variant must remain consistent in future requests for that ID.
Requests with an inconsistent product_variant for the same ID will return 400
default_lease_id (required) The default leases[] entry for the user.
(for HOA users, this represents the default unit)

↔️ Cross-reference
This value references a leases[] entry and must match its lease_id value.
leases[] (required) Array of units for which the user is paying HOA fees.
At least one unit must be provided.

Fields are documented in the next section 👇

2️⃣ leases[] Array:

The Livble API was designed for flexible rent flows, where a tenant pays rent for a lease.
For HOA users, the same leases[] structure represents units, where the user pays HOA fees for a unit.

In other words, when working with HOA users, a lease in the API should be thought of as an HOA unit.

The table below documents all fields within a leases[] entry and explains how to populate them for HOA users.

🏷️ Field ⚙️ How to populate
lease_id The ID of the HOA unit.

📌 Must be provided for the default HOA unit.
lease_status Omit or set null
unit_id Omit or set null.

✅ This field can be safely omitted.
As described above, the lease_id field serves as the unit identifier for HOA users.
landlord_id Omit or set null
lease_start Omit or set null
lease_end Omit or set null
lease_end_action Omit or set null
autopay_amount_in_cents Monthly autopay amount for the unit's HOA fees, in cents.

Autopay disabled → omit this field or set it to null
Autopay enabled → set the monthly amount in cents
Autopay enabled but amount is unknown → set 1

📖 For more details, see our Autopay guide.
partial_payments_allowed This field behaves the same as for flexible rent users.

📖 For more details, see the Updating Tenant Data guide.
payments_enabled Indicates whether online payments are enabled for the unit's HOA fees.
open_balance (required) The current open balance of HOA fees for the unit.

This field behaves the same as for flexible rent users.
charges (required) Past, current, and future HOA charges for the unit.

This field behaves the same as for flexible rent users.
historical_payments (required) Past HOA payments made by the user for the unit.

This field behaves the same as for flexible rent users.
address The address of the unit.

📌 Must be provided for the default HOA unit.
rent_due_day Day of the month when the monthly HOA payments are due.
base_rent_amount_in_cents The base recurring HOA fee amount charged monthly, in cents.
(excluding one-time/special charges)

📦 Full step-by-step payload

This section walks through a complete /portal_info payload for an HOA user, step by step, to provide a big-picture view of how all fields fit together.


Updated about 2 months ago