LotWize API Documentation

Last updated: May 2026

Welcome to the LotWize API. This documentation covers authentication, endpoints, rate limits, error handling, webhooks, and SDK availability.

---

Overview

The LotWize API is a REST API that lets you:

• Manage members and users
• Process payments
• Handle violations
• Schedule and manage meetings
• Store and retrieve documents
• Generate reports
• Receive real-time events via webhooks

Base URL:

https://api.lotwize.com/v1

All API requests must be made over HTTPS. HTTP requests are automatically redirected to HTTPS.

---

Authentication

API Keys

All requests require an API key passed in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lotwize.com/v1/members

Getting an API key:

1. Log in to your LotWize account
2. Go to Settings → API
3. Click "Generate API Key"
4. Copy the key (shown once — save it safely)

API key types:

Security:

• API keys are scoped to your organization
• Never share your API key
• Never expose keys in client-side code (JavaScript in browsers)
• Rotate keys regularly in Settings → API

Webhook Authentication

Webhooks sent by LotWize include a signature for verification:

X-LotWize-Signature: sha256=abcdef123456...

Verify the signature using your webhook secret:

import hmac
import hashlib

expected = hmac.new(
  webhook_secret.encode(),
  request_body.encode(),
  hashlib.sha256
).hexdigest()

if not hmac.compare_digest(f"sha256={expected}", request_signature):
  raise ValueError("Invalid signature")

---

Rate Limits

Rate limits prevent abuse and ensure platform stability.

Limits by Plan

What counts: Every HTTP request (GET, POST, PATCH, DELETE) counts as one request.

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1715769600

When you hit the limit:

• Response code: 429 Too Many Requests
• Response body: { "error": "Rate limit exceeded", "retry_after": 45 }
• Wait the specified seconds before retrying

Best practices:

• Cache responses when possible
• Use webhooks instead of polling
• Batch operations when available
• Implement exponential backoff for retries

---

Common Endpoints

Members

Manage homeowners, board members, and users.

List members:

GET /api/members?page=1&limit=50&role=homeowner

Response:

{
  "data": [
    {
      "id": "mem_123abc",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "homeowner",
      "unit": "42B",
      "status": "active",
      "created_at": "2025-03-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 127,
    "has_more": true
  }
}

Create member:

POST /api/members
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "homeowner",
  "unit": "12A",
  "phone": "555-123-4567"
}

Update member:

PATCH /api/members/mem_123abc
Content-Type: application/json

{
  "phone": "555-987-6543",
  "status": "active"
}

Delete member:

DELETE /api/members/mem_123abc

Filters:

• role — homeowner, board, pmc, admin
• status — active, pending, suspended
• unit — specific unit number
• created_after — ISO 8601 date

---

Payments

Process and query payments.

List payments:

GET /api/payments?status=completed&start_date=2026-04-01&end_date=2026-04-30

Create payment:

POST /api/payments
Content-Type: application/json

{
  "member_id": "mem_123abc",
  "amount": 25000,
  "currency": "usd",
  "type": "dues",
  "description": "April 2026 HOA dues"
}

Note: Amount is in cents ($250.00 = 25000)

Payment statuses:

• pending — Payment initiated, awaiting confirmation
• completed — Successfully processed
• failed — Payment did not go through
• refunded — Full refund issued
• partially_refunded — Partial refund issued

Webhooks: Payment status changes trigger payment.updated events.

---

Violations

Manage violation notices.

List violations:

GET /api/violations?status=open&severity=high

Create violation:

POST /api/violations
Content-Type: application/json

{
  "member_id": "mem_123abc",
  "rule_id": "rule_456def",
  "description": "Unapproved fence installation",
  "severity": "medium",
  "fine_amount": 5000,
  "cure_period_days": 14,
  "evidence_urls": ["https://.../photo1.jpg"]
}

Update violation status:

PATCH /api/violations/vio_789ghi
Content-Type: application/json

{
  "status": "resolved",
  "resolution_notes": "Homeowner removed fence on 2026-05-01"
}

Violation statuses:

• open — Issued, awaiting response
• acknowledged — Homeowner acknowledged
• in_hearing — Scheduled for board hearing
• resolved — Issue fixed or fine paid
• escalated — Legal action pending
• closed — Final status, no further action

---

Meetings

Schedule and manage meetings.

List meetings:

GET /api/meetings?upcoming=true&community_id=org_abc123

Create meeting:

POST /api/meetings
Content-Type: application/json

{
  "title": "May 2026 Board Meeting",
  "type": "board",
  "start_time": "2026-05-15T19:00:00Z",
  "end_time": "2026-05-15T21:00:00Z",
  "location": "Community Center, 123 Main St",
  "agenda": "Budget review, landscaping proposal, violation appeals",
  "attendees": ["mem_123abc", "mem_456def"]
}

Meeting types:

• board — Board of directors meeting
• annual — Annual homeowners meeting
• special — Special/emergency meeting
• committee — Committee meeting

---

Documents

Upload and manage documents.

List documents:

GET /api/documents?folder=bylaws&visibility=public

Upload document:

POST /api/documents
Content-Type: multipart/form-data

file: <binary file data>
name: "Updated Bylaws 2026.pdf"
folder: "bylaws"
visibility: "public"
tags: ["governance", "2026"]

Supported formats: PDF, DOC, DOCX, XLS, XLSX, JPG, PNG, TXT

Max file size: 50MB per file

Visibility:

• public — Visible to all homeowners
• private — Board and PMC only
• restricted — Specific users only

---

Reports

Generate and export reports.

Request report:

POST /api/reports
Content-Type: application/json

{
  "type": "financial_summary",
  "community_id": "org_abc123",
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  },
  "format": "pdf"
}

Report types:

• financial_summary — Income, expenses, balances
• ar_aging — Accounts receivable aging
• violation_summary — Violations by status and type
• payment_history — All payments with details
• member_directory — Homeowner contact list
• meeting_minutes — Meeting records

Formats: pdf, csv, xlsx

Async reports: Large reports are processed asynchronously. The response includes a report_id for status checking:

GET /api/reports/status/rep_789xyz

---

Stripe Webhooks

Receive real-time payment events from Stripe.

Endpoint:

POST /api/stripe/webhook

Events we send:

Webhook payload example:

{
  "event": "payment_intent.succeeded",
  "timestamp": "2026-05-08T14:23:00Z",
  "data": {
    "payment_id": "pay_abc123",
    "member_id": "mem_456def",
    "amount": 25000,
    "currency": "usd",
    "status": "completed",
    "receipt_url": "https://lotwize.com/receipts/pay_abc123"
  }
}

Retry policy: If your webhook endpoint returns a non-200 status, we retry:

• Immediately
• After 5 minutes
• After 15 minutes
• After 1 hour
• After 4 hours
• Then we stop and log the failure

---

Error Codes

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request body contains invalid data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ],
    "request_id": "req_abc123def456",
    "documentation_url": "https://docs.lotwize.com/errors/invalid_request"
  }
}

Common Error Codes

---

Webhook Events

Full Event Catalog

Payment Events

• payment.created
• payment.updated
• payment.completed
• payment.failed
• payment.refunded

Member Events

• member.created
• member.updated
• member.deleted
• member.suspended
• member.activated

Violation Events

• violation.created
• violation.updated
• violation.resolved
• violation.escalated

Meeting Events

• meeting.created
• meeting.updated
• meeting.reminder (24h before)
• meeting.cancelled

Document Events

• document.uploaded
• document.updated
• document.deleted

Organization Events

• organization.created
• organization.updated
• organization.trial_started
• organization.trial_ended
• organization.subscribed
• organization.cancelled

Setting Up Webhooks

1. Go to Settings → API → Webhooks
2. Click "Add Webhook Endpoint"
3. Enter your endpoint URL (must be HTTPS)
4. Select events to subscribe to
5. Save — we send a test event immediately

Testing webhooks locally: Use ngrok to expose localhost:

ngrok http 3000
# Use the HTTPS URL as your webhook endpoint

---

SDK Availability

Official SDKs

JavaScript SDK Example

import { LotWize } from '@lotwize/sdk';

const client = new LotWize({
  apiKey: 'your_api_key_here',
  baseUrl: 'https://api.lotwize.com/v1'
});

// List members
const members = await client.members.list({
  role: 'homeowner',
  limit: 50
});

// Create a payment
const payment = await client.payments.create({
  memberId: 'mem_123abc',
  amount: 25000, // cents
  type: 'dues',
  description: 'May 2026 dues'
});

// Handle webhooks
app.post('/webhooks/lotwize', (req, res) => {
  const event = client.webhooks.verify(req.body, req.headers['x-lotwize-signature']);
  
  if (event.type === 'payment.completed') {
    console.log(`Payment ${event.data.payment_id} completed!`);
  }
  
  res.status(200).send('OK');
});

Python SDK Example

from lotwize import LotWize

client = LotWize(api_key="your_api_key_here")

# List members
members = client.members.list(role="homeowner", limit=50)

# Create a violation
violation = client.violations.create(
    member_id="mem_123abc",
    rule_id="rule_456def",
    description="Unauthorized modification",
    severity="medium",
    fine_amount=5000
)

# Generate a report
report = client.reports.create(
    type="financial_summary",
    community_id="org_abc123",
    date_range={"start": "2026-04-01", "end": "2026-04-30"},
    format="pdf"
)

---

API Versioning

The current API version is v1.

Version in URL:

https://api.lotwize.com/v1/...

Deprecation policy:

• We notify all API users 6 months before deprecating an endpoint
• Deprecated endpoints continue working for 3 months after the notice
• Breaking changes only happen in major version bumps (v1 → v2)
• New features are added to the current version without breaking existing ones

Changelog: Subscribe to API updates at lotwize.com/api-changelog.

---

Support

• 📧 API Support: support@sanafai.com
• 💬 Developer Slack: lotwize.dev/slack
• 🐛 Report Issues: GitHub Issues
• 📚 Full Reference: docs.lotwize.com/api

---

Ready to build? Generate your API key in Settings → API and make your first request!