Units & Tenants API
Handle rental units and tenant information. Manage unit details, tenant assignments, and relationships between properties, units, and tenants.
Units & Tenants
Units are containers for tenants. You manage tenants through their associated unit.
GET /units/:unitId: Get a single unit.Response Format
{ "id": "string", "propertyId": "string", "label": "string", "sqft": "number (decimal)", "bedrooms": "number (integer)", "monthlyRent": "number (decimal)", "isActive": "boolean", "createdAt": "string (ISO date)", "updatedAt": "string (ISO date)", "tenants": [ { "id": "string", "unitId": "string", "name": "string", "email": "string", "createdAt": "string (ISO date)", "updatedAt": "string (ISO date)" } ] }PATCH /units/:unitId: Update a unit.Request Body
// All fields are optional. { "label": "string", "sqft": "number (decimal)", "bedrooms": "number (integer)", "monthlyRent": "number (decimal)" }DELETE /units/:unitId: Delete a unit.Response Format
{ "message": "string", "isDeactivated": "boolean" }POST /units/:unitId/tenants: Create a new tenant for a unit.Request Body
{ "name": "string (required)", "email": "string (email format, optional)" }GET /units/:unitId/tenants: List all tenants for a unit.Response Format
[ { "id": "string", "unitId": "string", "name": "string", "email": "string", "createdAt": "string (ISO date)", "updatedAt": "string (ISO date)" } ]GET /tenants/:tenantId: Get a single tenant.Response Format
{ "id": "string", "unitId": "string", "name": "string", "email": "string", "createdAt": "string (ISO date)", "updatedAt": "string (ISO date)" }PATCH /tenants/:tenantId: Update a tenant.Request Body
// All fields are optional. { "name": "string", "email": "string (email format)" }DELETE /tenants/:tenantId: Delete a tenant.Response Format
{ "message": "string" }
Code Examples
Units & Tenants API
Examples for managing units and tenants programmatically.
Get Unit Details
import requests
# Get a specific unit with tenants
unit_id = "your_unit_id_here"
response = requests.get(
f"https://app.billgauge.com/api/v1/units/{unit_id}",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
if response.status_code == 200:
unit = response.json()
print(f"Unit: {unit['label']}")
print(f"Square Feet: {unit['sqft']}")
print(f"Bedrooms: {unit['bedrooms']}")
print(f"Monthly Rent: {unit['monthlyRent']}")
print(f"Tenants: {len(unit['tenants'])}")
for tenant in unit['tenants']:
print(f" - {tenant['name']} ({tenant['email']})")
else:
print(f"Error: {response.status_code} - {response.text}")Update Unit
import requests
# Update unit details
unit_id = "your_unit_id_here"
update_data = {
"label": "Unit A - Updated",
"sqft": 850.5,
"bedrooms": 2,
"monthlyRent": 1200.00
}
response = requests.patch(
f"https://app.billgauge.com/api/v1/units/{unit_id}",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json=update_data
)
if response.status_code == 200:
updated_unit = response.json()
print(f"Updated unit: {updated_unit['label']}")
else:
print(f"Error: {response.status_code} - {response.text}")List Tenants for Unit
import requests
# Get all tenants for a specific unit
unit_id = "your_unit_id_here"
response = requests.get(
f"https://app.billgauge.com/api/v1/units/{unit_id}/tenants",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
if response.status_code == 200:
tenants = response.json()
print(f"Found {len(tenants)} tenants:")
for tenant in tenants:
print(f" - {tenant['name']} ({tenant['email']})")
print(f" ID: {tenant['id']}")
print(f" Created: {tenant['createdAt']}")
else:
print(f"Error: {response.status_code} - {response.text}")Create New Tenant
import requests
# Create a new tenant for a unit
unit_id = "your_unit_id_here"
tenant_data = {
"name": "John Doe",
"email": "[email protected]"
}
response = requests.post(
f"https://app.billgauge.com/api/v1/units/{unit_id}/tenants",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json=tenant_data
)
if response.status_code == 201:
new_tenant = response.json()
print(f"Created tenant: {new_tenant['name']}")
print(f"Tenant ID: {new_tenant['id']}")
else:
print(f"Error: {response.status_code} - {response.text}")Update Tenant
import requests
# Update tenant information
tenant_id = "your_tenant_id_here"
update_data = {
"name": "John Smith",
"email": "[email protected]"
}
response = requests.patch(
f"https://app.billgauge.com/api/v1/tenants/{tenant_id}",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json=update_data
)
if response.status_code == 200:
updated_tenant = response.json()
print(f"Updated tenant: {updated_tenant['name']}")
print(f"New email: {updated_tenant['email']}")
else:
print(f"Error: {response.status_code} - {response.text}")Delete Tenant
import requests
# Delete a tenant
tenant_id = "your_tenant_id_here"
response = requests.delete(
f"https://app.billgauge.com/api/v1/tenants/{tenant_id}",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
if response.status_code == 200:
result = response.json()
print(result['message'])
else:
print(f"Error: {response.status_code} - {response.text}")Delete Unit
import requests
# Delete a unit (will be deactivated if it has financial data)
unit_id = "your_unit_id_here"
response = requests.delete(
f"https://app.billgauge.com/api/v1/units/{unit_id}",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
if response.status_code == 200:
result = response.json()
print(result['message'])
if result['isDeactivated']:
print("Unit was deactivated (has historical data)")
else:
print("Unit was permanently deleted")
else:
print(f"Error: {response.status_code} - {response.text}")