AppFolio CI Integration

Overview

Configure CI pipelines that validate AppFolio property management API integrations using a two-tier strategy. Unit tests mock the AppFolio REST client to verify tenant lookup, work order creation, and property listing logic without consuming API quota. Integration tests run against the AppFolio sandbox environment on main-branch merges only, using Basic Auth credentials stored as GitHub secrets. This keeps PR feedback fast and free while catching real API contract drift before production deploys.

Prerequisites

• A repository with Actions enabled, a locked dependency install, and unit tests that use only synthetic tenant, property, and work-order fixtures.
• A separately managed AppFolio sandbox credential and a pre-provisioned, non-production fixture record that the integration owner is allowed to read.
• Defined CI ownership, a fixed request budget, and an incident path for credential rotation, provider outage, or sandbox data reset.

Instructions

1. Keep pull-request checks mock-only; do not expose AppFolio credentials to untrusted code or forked pull requests.
2. Gate the live sandbox job to protected main pushes after lint, type, and unit checks pass, and inject credentials only through repository secrets.
3. Limit the integration run to a known read-only fixture, one worker, and the stated request budget; record only redacted status and count evidence.
4. Treat failed authentication, rate limits, or missing fixtures as a blocked release condition rather than creating shared sandbox data from CI.

GitHub Actions Workflow

# .github/workflows/appfolio-tests.yml
name: AppFolio API Tests
on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run lint && npm run typecheck
      - run: npm test -- --testPathPattern=unit  # No API credentials needed

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --testPathPattern=integration
        env:
          APPFOLIO_CLIENT_ID: ${{ secrets.APPFOLIO_CLIENT_ID }}
          APPFOLIO_CLIENT_SECRET: ${{ secrets.APPFOLIO_CLIENT_SECRET }}
          APPFOLIO_BASE_URL: ${{ secrets.APPFOLIO_SANDBOX_URL }}

Mock-Based Unit Tests

// tests/unit/work-order-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createWorkOrder } from '../../src/services/work-order-…

AppFolio Common Errors

Overview

AppFolio's Stack API powers property management integrations for tenant screening, work orders, lease management, and accounting. Each portfolio operates under its own subdomain ({company}.appfolio.com), meaning a single integration may need to handle multiple base URLs. Errors commonly stem from authentication misconfiguration, incorrect base URLs per portfolio, and business logic violations like duplicate tenant records or conflicting lease dates. Tenant lookup failures (404) are the most frequent issue, typically caused by targeting the wrong portfolio subdomain. This reference covers HTTP-level failures, property-management-specific validation errors, and recovery patterns for the most frequently encountered issues.

Prerequisites

• A redacted incident record containing the portfolio identifier, endpoint, status code, request correlation ID, and time window; never copy tenant or lease payloads into a shared ticket.
• Access to the correct sandbox or production portfolio endpoint and a credential owner who can rotate or validate credentials without exposing them in logs or command arguments.
• A bounded retry policy, an idempotency mechanism for writes, and a known operator escalation path for uncertain tenant, lease, or work-order state.

Instructions

1. Classify the response by authentication, rate-limit, validation, or server failure and preserve only the redacted diagnostic fields.
2. Verify the portfolio base URL before changing credentials or retrying a 404; a valid tenant ID in another portfolio is not evidence of absence.
3. For 409 or partial write failures, query the canonical record and use the operation’s idempotency key or operator review before issuing another write.
4. Honor Retry-After for 429 and stop after the configured retry budget; pause the batch on 5xx or unknown write outcomes.

Error Reference

AppFolio — Property & Tenant Management

Overview

Primary workflow for AppFolio property management integration. Covers the full property lifecycle: creating and updating property records, managing tenant profiles and lease agreements, and querying occupancy data. Uses the AppFolio Stack API with OAuth 2.0 client credentials for server-to-server access. All endpoints return JSON and support pagination via cursor parameters for large portfolios.

Prerequisites

• A current AppFolio partner/API contract that confirms the assigned portfolio base URL, authentication method, approved scopes, and write capabilities; do not infer these from a tutorial or another portfolio.
• A separate sandbox with disposable properties, units, and synthetic tenant records, plus a credential owner and an approved request budget.
• Idempotency keys and an operator-approved rollback/reconciliation process for property, tenant, and lease writes, which can create real legal and billing consequences.

Instructions

1. Confirm the provider-issued base URL and authentication flow for the target portfolio before copying any client configuration into an environment.
2. Exercise the create/update path only with sandbox synthetic fixtures and idempotency keys; retrieve canonical records before retrying an uncertain write.
3. Validate ownership, lease dates, and unit availability before creating a lease, and emit only record IDs and redacted status evidence.
4. Promote a write-capable flow only after a staged rehearsal proves rollback, reconciliation, and the least-privilege scope boundary.

Step 1: Authenticate and Initialize Client

const token = await fetch('https://api.appfolio.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.APPFOLIO_CLIENT_ID!,
    client_secret: process.env.APPFOLIO_CLIENT_SECRET!,
    scope: 'properties tenants leases',
  }),
}).then(r => r.json());
const headers = { Authorization: `Bearer ${token.access_token}`, 'Content-Type': 'application/json' };

Step 2: Create or Update a Property

const property = await fetch('https://api.appfolio.com/v1/properties', {
  method: 'POST', headers,
  body: JSON.stringify({
    name: 'Sunrise Apartments',
    address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
    type: 'residential',
    units: [
      { number: '101', bedrooms: 2, bathrooms: 1, rent: 1450 },
      { number: '102', bedrooms: 1, bathrooms: 1, rent: 1100 },
    ],
  }),
}).then(r => r.json());
console.l…

AppFolio — Work Orders & Maintenance

Overview

Manage the full lifecycle of maintenance work orders through AppFolio's Stack API. Use this workflow when tenants submit maintenance requests, when you need to assign vendors to open work orders, track repair progress across properties, or close out completed jobs with cost records. This is the secondary workflow — for property dashboards and leasing, see appfolio-core-workflow-a.

Prerequisites

• A verified AppFolio contract and sandbox portfolio with synthetic property, unit, vendor, and work-order records; do not test maintenance automation against an occupied production unit.
• A least-privilege service identity, idempotency support for create/close actions, and an approved escalation path for safety-critical maintenance.
• A data-minimization policy: store and transmit only the maintenance facts needed to perform work, never tenant preferences, access codes, or detailed occupancy information in generic vendor notes or logs.

Instructions

Step 1: Create a Work Order from a Maintenance Request

const workOrder = await client.workOrders.create({
  property_id: 'prop_4821',
  unit_id: 'unit_12B',
  category: 'plumbing',
  priority: 'high',
  description: 'Synthetic plumbing fixture leak reported in sandbox unit',
  requested_by: 'tenant_8934',
  due_date: '2026-04-10',
});
console.log(`Work order ${workOrder.id} created — status: ${workOrder.status}`);

Step 2: Assign a Vendor

const assignment = await client.workOrders.assign(workOrder.id, {
  vendor_id: 'vendor_plumb_01',
  scheduled_date: '2026-04-08',
  time_window: '09:00-12:00',
  notes: 'Confirm scheduled appointment through the approved work-order channel.',
});
console.log(`Assigned to ${assignment.vendor_name} on ${assignment.scheduled_date}`);

Step 3: Track Work Order Status

const open = await client.workOrders.list({
  property_id: 'prop_4821',
  status: ['open', 'in_progress', 'scheduled'],
  sort: 'priority_desc',
});
open.items.forEach(wo =>
  console.log(`#${wo.id} [${wo.priority}] ${wo.category} — ${wo.status} (due ${wo.due_date})`)
);

Step 4: Close Work Order with Cost Record

const closed = await client.workOrders.close(workOrder.id, {
  resolution: 'Replaced P-trap and tightened supply line. No further leaks.',
  labor_cost: 175.00,
  materials_cost: 42.50,
  completed_date: '2026-04-08',
  attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`Closed #${closed.id} — total cost: $${closed.total_cost}`);

Error Handling

AppFolio Cost Tuning

Overview

AppFolio Stack API pricing is partner-agreement based, with costs scaling by API call volume per managed property. Property management portfolios generate high-frequency reads for tenant lookups, lease status checks, and maintenance requests. Each redundant API call erodes margin on per-unit revenue. Optimizing call patterns directly impacts operational profitability, especially for portfolios managing hundreds or thousands of units where even small per-call costs compound rapidly.

Prerequisites

• The current partner agreement’s actual billing, endpoint quota, export, and event-delivery terms; treat published examples as planning inputs, not price commitments.
• A data classification and retention policy that prevents tenant, lease, and financial payloads from being retained in generic process memory or caches.
• Per-endpoint call budgets, cache owners, and a reconciliation path for stale reads that could affect accounting, lease, or maintenance decisions.

Instructions

1. Measure the existing call rate, cache hit rate, payload sizes, and provider charges by endpoint before changing a TTL or polling interval.
2. Cache only the minimized, non-sensitive fields required by the caller, with a bounded size and an endpoint-specific freshness policy.
3. Use incremental reads or provider-supported events only after verifying the partner capability and loss/replay semantics; otherwise use bounded polling.
4. Stop or degrade non-critical work at the approved budget threshold and send stale or incomplete financial/lease data to an operator rather than guessing.

Cost Breakdown

API Call Reduction

class AppFolioCache {
  private cache = new Map<string, { data: unknown; expiry: number }>();
  private readonly maxEntries = 1_000;

  get(key: string): any | null {
    const entry = this.cache.get(key);
    if (!entry || Date.now() > entry.expiry) return null;
    return entry.data;
  }

  set…

AppFolio Debug Bundle

Overview

This debug bundle collects diagnostic evidence from AppFolio property management API integrations for support escalation and root cause analysis. It captures API connectivity against the properties, tenants, and work orders endpoints, authentication status using client credential pairs, recent error logs from integration pipelines, and SDK version information. The resulting tarball gives support engineers everything they need to diagnose connectivity failures, auth rejections, and data sync issues without requiring live access to your environment.

Prerequisites

• curl, jq, tar installed
• APPFOLIO_CLIENT_ID and APPFOLIO_CLIENT_SECRET configured (basic auth pair)
• APPFOLIO_BASE_URL set to your Stack API base (e.g., https://yourcompany.appfolio.com/api/v1)

Instructions

1. Obtain incident approval and define the affected time window, portfolio, and safe-read probes; do not collect tenant, lease, payment, or raw log bodies merely because they are available.
2. Create the bundle with redacted configuration state, provider status/latency, rate-limit headers, and package versions only; keep credentials out of argv.
3. Review every file before sharing, encrypt or use the approved support channel for the archive, and delete the local copy according to the incident policy.
4. If evidence requires sensitive records, stop and obtain a separately approved minimal export rather than expanding this general-purpose debug bundle.

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
  "$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"

probe() {
  endpoint="$1"
  curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
    --netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
    || printf 'UNREACHABLE\n'
}

# Environment check
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo '…

AppFolio Deploy Integration

Overview

Deploy a containerized AppFolio property management integration service with Docker. This skill covers building a production-ready image that connects to the AppFolio Stack API for managing properties, tenants, and work orders. Includes environment configuration for multi-property setups, health checks that verify API connectivity, and rolling update strategies for zero-downtime deployments across your property portfolio.

Prerequisites

• A verified provider contract and a secret-manager-backed, contract-bound AppFolio client; do not put credential values in image layers, compose files, shell history, or deployment logs.
• A deployment platform that can perform a real rolling/canary update with readiness checks, traffic control, rollback, and a named release owner.
• Separate staging and production identities, a synthetic staging smoke fixture, and an incident plan for unknown write or reconciliation state.

Instructions

1. Build a non-root image with locked dependencies and expose only a local liveness endpoint; provider availability belongs to readiness, not process survival.
2. Inject the verified client configuration at runtime from the secret manager and validate its contract in staging through an authorized safe read.
3. Roll out a new revision gradually, monitor redacted readiness/error signals, and retain the prior revision until the traffic window succeeds.
4. On any failed readiness, contract, secret, or reconciliation check, halt traffic promotion and roll back through the deployment platform.

Docker Configuration

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "dist/index.js"]

Runtime Configuration

# Values are injected by the deployment platform's secret manager; do not
# paste live credentials into a terminal command or checked-in configuration.
APPFOLIO_BASE_URL="provider-issued base URL"
APPFOLIO_COMPANY_ID="approved portfolio identifier"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"

Health Check Endpoint

import express from 'express';

const app = express();

// Liveness proves this process can…

AppFolio Hello World

Overview

Get started with the AppFolio Property Manager API through a verified provider-issued client configuration. This skill walks through safe first reads for a property listing and a tenant count; create or update operations belong only in a separately approved synthetic sandbox workflow.

Prerequisites

• AppFolio Stack Partner account with API access
• A managed, provider-issued base URL and authentication client confirmed for the target portfolio; do not use a guessed hostname or credential scheme
• Node.js 18+ and TypeScript

Instructions

Step 1: Configure the Client

async function appfolioFetch(path: string) {
  const res = await createVerifiedAppFolioClient().get(path);
  if (res.status < 200 || res.status >= 300) throw new Error(`AppFolio ${res.status}`);
  return res.data;
}

Step 2: List Properties

const properties = await appfolioFetch("/properties?page_size=10");
console.log(`Found ${properties.length} properties`);
properties.forEach((p: any) => console.log(`  property ID: ${p.id}`));

Step 3: Get Tenant Details

const tenants = await appfolioFetch(`/tenants?property_id=${properties[0].id}`);
console.log(`Retrieved ${tenants.length} tenant records for the approved fixture`);

Step 4: Stop Before Writes

// Do not create a work order as a quickstart test. Continue only with the
// synthetic, idempotent workflow in appfolio-core-workflow-b.

Output

A successful run proves the managed client and an approved safe-read endpoint work, returning only property IDs and a tenant-record count in its local output.

Examples

For a first integration check, configure the verified sandbox client, query one approved synthetic property page, and confirm its status, property IDs, and tenant count without recording addresses, names, unit numbers, or credentials. Do not create a work order merely to test access. If the portfolio contract, safe-read fixture, or response authorization is not verified, stop the run and use the credential owner’s staging process before attempting any mutation.

Error Handling

AppFolio Install & Auth

Overview

Configure AppFolio Stack API authentication. AppFolio uses HTTP Basic Auth with a client ID and client secret, provided through their Stack partner program. No public npm SDK exists — use direct REST API calls.

Prerequisites

• AppFolio Stack partner account (appfolio.com/stack)
• Client ID and Client Secret from AppFolio
• Node.js 18+ or Python 3.10+

Instructions

Step 1: Obtain API Credentials

# AppFolio Stack API credentials come from the partner program
# 1. Apply at appfolio.com/stack/become-a-partner
# 2. Complete integration review
# 3. Receive the provider-issued base URL and credential delivery instructions.
# Store the values in the approved secret manager. Commit only this non-secret
# template if local development requires one:
cat > .env.example << 'ENVFILE'
APPFOLIO_CLIENT_ID=
APPFOLIO_CLIENT_SECRET=
APPFOLIO_BASE_URL=
ENVFILE

# .env remains ignored; populate it only through an approved local secret flow.

Step 2: Create API Client

// src/appfolio-client.ts
import axios, { AxiosInstance } from 'axios';

class AppFolioClient {
  private api: AxiosInstance;

  constructor() {
    this.api = axios.create({
      baseURL: process.env.APPFOLIO_BASE_URL,
      auth: {
        username: process.env.APPFOLIO_CLIENT_ID!,
        password: process.env.APPFOLIO_CLIENT_SECRET!,
      },
      headers: { 'Content-Type': 'application/json' },
      timeout: 30000,
    });
  }

  async verifyConnection(): Promise<boolean> {
    try {
      const response = await this.api.get('/properties');
      console.log(`Connected! Found ${response.data.length} properties`);
      return true;
    } catch (error: any) {
      console.error(`Connection failed: ${error.response?.status} ${error.message}`);
      return false;
    }
  }

  get http(): AxiosInstance { return this.api; }
}

export { AppFolioClient };

Step 3: Verify Connection

# Quick, redacted diagnostic without putting Basic Auth in argv.
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
  "$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
curl -s -o /dev/null -w '%{http_code}\n' --netrc-file "$NETRC_FILE" \
  "${APPFOLIO_BASE_URL}/properties"

API Endpoints

AppFolio Local Dev Loop

Overview

Local development workflow for AppFolio property management API integration. Provides a fast feedback loop with mock property, tenant, and lease endpoints so you can build and test integrations without consuming live API quota. Toggle between mock mode for rapid iteration and sandbox mode for pre-deployment validation against the real AppFolio Stack API.

Prerequisites

• A mock-only local environment with synthetic property, tenant, lease, and work-order fixtures that contain no production addresses, names, or payments.
• A separately managed sandbox credential and an approved safe-read fixture for the dedicated integration lane; it is never loaded by the local dev server.
• A log policy that records request shape and status only, plus an explicit owner for sandbox quota, fixture reset, and credential rotation.

Instructions

1. Run the local server only in mock mode and exercise reads/writes against synthetic routes with deterministic fixtures.
2. Test request validation, idempotency, redaction, and error handling in unit tests before any sandbox connectivity check.
3. Run the sandbox lane separately with the contract-bound managed client and one authorized safe-read fixture; do not turn a local proxy into a live API tunnel.
4. Stop when the fixture, credentials, request budget, or output redaction is unverified, then correct the environment before continuing.

Environment Setup

cp .env.example .env
# Leave provider credentials blank locally. Mock mode is the default.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("Local server is mock-only; use the managed sandbox integration lane");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio dev server on :3001 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic property management responses
export function mountMockRoutes(app: any) {
  app.get("/api/v1/properties", (_req: any, res: any) => res.json([
    { id: "prop_1", name: "Sunset Apartments", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
    { id: "prop_2", name: "Downtown Office", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commerc…

AppFolio Performance Tuning

Overview

AppFolio's property management API handles bulk tenant queries, property portfolio pagination, and work order batch processing. Large portfolios with thousands of units generate heavy read traffic on listing endpoints. Optimizing cache lifetimes for slow-changing property data, batching work order updates, and pooling HTTP connections reduces API call volume by 60-80% and cuts dashboard load times from seconds to sub-second.

Prerequisites

• A measured baseline for latency, call volume, error rate, payload size, cache hit behavior, and data freshness for the specific permitted endpoint.
• Endpoint-specific rate/concurrency limits, a request budget, and a data policy that excludes tenant, payment, and raw response payloads from generic caches.
• Synthetic fixtures and a rollback feature flag for validating performance changes without altering production read/write semantics.

Instructions

1. Start with the smallest safe read and capture a baseline before changing caching, concurrency, pagination, or connection settings.
2. Cache only minimized data under a bounded entry/byte policy and invalidate on known writes; show stale age to callers where decisions need freshness.
3. Respect the smallest endpoint limit, preserve cursors, and stop parallel batches before they turn a rate-limit signal into a retry storm.
4. Promote only when performance improves without changing result completeness, authorization, PII boundaries, or write/idempotency behavior; roll back on any correctness regression.

Caching Strategy

const cache = new Map<string, { data: unknown; expiry: number }>();
const MAX_CACHE_ENTRIES = 1_000;
const TTL = { properties: 300_000, tenants: 120_000, units: 300_000, workOrders: 60_000 };

async function cached(key: string, ttlKey: keyof typeof TTL, fn: () => Promise<any>) {
  const entry = cache.get(key);
  if (entry && entry.expiry > Date.now()) return entry.data;
  const data = await fn();
  if (!cache.has(key) && cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value!);
  cache.set(key, { data, expiry: Date.now() + TTL[ttlKey] });
  return data;
}

Batch Operations

async function batchWorkOrders(client: any, ids: string[], batchSize = 25) {
  const results = [];
  for (let i = 0; i < ids.length; i += batchSize) {
    const batch = ids.slice(i, i + batchSize);
    const res = await Promise.all(batch.map(id => client.http.get(`/work_orders/${id}`)));
    results.push(...res.map(r => r.data));
    if (i + batchSize < ids.length) await new Promise(r => setTimeout(r, 200));
  }
  return results;
}

Connection Pooling

import { Agent } from 'https';
const …

AppFolio Production Checklist

Overview

AppFolio manages properties, tenants, leases, and work orders for real estate operations. A production integration handles sensitive tenant PII, financial transactions, and maintenance workflows. Failures here mean missed rent collections, unprocessed work orders, or tenant data exposure under CCPA. This checklist ensures your AppFolio API integration is resilient, compliant, and observable.

Prerequisites

• A verified production partner contract, base URL, auth mechanism, permitted endpoint scopes, and named owners for business, security, operations, and rollback decisions.
• A completed sandbox rehearsal using synthetic data, separate managed credentials, a request budget, and a recorded rollback/reconciliation plan.
• Evidence for observability, PII minimization, idempotent writes, and alert routing—not a checklist item that merely asserts those controls exist.

Instructions

1. Validate the actual provider-issued client configuration through the secret manager; do not default an endpoint or authentication scheme in release code.
2. Run the readiness checks in staging, then a controlled production-shaped rehearsal that performs only authorized safe reads.
3. Review every failed, skipped, or unverifiable control as a no-go; preserve redacted receipts for credentials, endpoints, monitoring, and recovery.
4. Release progressively only with a tested rollback and reconciliation owner; pause write paths if payment, work-order, tenant, or lease state is unknown.

Authentication & Secrets

• [ ] APPFOLIO_API_KEY stored in secrets manager (not environment files)
• [ ] Client ID and secret separated from application code
• [ ] Key rotation schedule documented (90-day recommended)
• [ ] Separate credentials for dev/staging/prod environments
• [ ] API credentials scoped to minimum required permissions

API Integration

• [ ] Production base URL and authentication method verified against the current partner contract
• [ ] Rate limit handling with exponential backoff
• [ ] Pagination implemented for property and tenant list endpoints
• [ ] Work order creation tested with all required fields
• [ ] Lease document upload validated for supported formats
• [ ] Webhook endpoints configured for tenant and payment events
• [ ] Idempotency keys used for payment and work order creation

Error Handling & Resilience

• [ ] Circuit breaker configured for AppFolio API outages
• [ ] Retry with backoff for 429/5xx responses
• [ ] Tenant PII handling verified CCPA/FCRA compliant
• [ ] Data validation on all API responses before storage
• [ ] Graceful degradation when property sync is unavailable
• [ ] Duplicate work order detection p…

AppFolio Rate Limits

Overview

AppFolio's Stack API enforces per-partner rate limits to protect shared property management infrastructure. High-volume operations like bulk tenant imports, rent-roll syncs, and work-order batch updates can quickly exhaust quotas. Property managers running nightly portfolio syncs across hundreds of units must throttle carefully, especially during month-end when lease renewals and payment processing spike concurrently.

Prerequisites

• A verified per-endpoint limit from the current AppFolio partner contract or response headers; do not rely on a generic rate value for tenant writes.
• Persisted batch cursors, idempotency keys for every write, and an operator policy for pausing month-end or other safety-sensitive workloads.
• A staging fixture and request-budget owner who can prove retries, 429 behavior, and unknown-write handling without touching production tenants.

Instructions

1. Select the limiter ceiling for the specific endpoint and keep concurrency below the smallest applicable portfolio or partner limit.
2. Acquire a token before each request, honor Retry-After, and cap retries with jitter for transient provider failures.
3. Process writes from a persisted cursor with idempotency keys; never replay a tenant create just because the response was lost.
4. Pause and escalate batches that exhaust the retry budget, hit a maintenance window, or have an unknown write outcome.

Rate Limit Reference

Rate Limiter Implementation

class AppFolioRateLimiter {
  private tokens: number;
  private lastRefill: number;
  private readonly maxTokens: number;
  private readonly refillRate: number; // tokens per ms

  constructor(maxPerMinute: number) {
    this.maxTokens = maxPerMinute;
    this.tokens = maxPerMinute;
    this.lastRefill = Date.now();
    this.refillRate = maxPerMinute / 60_000;
  }

  async acquire(): Promise<void> {
    for (;;) {
      this.refill();
      if (this.tokens >= 1) {
        this.tokens -= 1;
        return;
      }
      // Wait until the next token is available; no later request is needed to
      // wake this caller.
      const waitMs = Math.max(1, Math.ceil((1 - this.tokens) / this.refillRate)…

AppFolio Reference Architecture

Overview

Production architecture for property management integrations with the AppFolio Stack API. Designed for multi-property portfolios requiring real-time vacancy tracking, tenant lifecycle management, work order routing, and accounting reconciliation. Key design drivers: data freshness for leasing decisions, idempotent sync for financial accuracy, and tenant-facing portal responsiveness.

Prerequisites

• A provider-verified contract for endpoints, authentication, events (if any), rate limits, data residency, and permitted downstream accounting/CRM effects.
• Separate staging and production environments with managed secrets, synthetic fixtures, durable queues/idempotency stores, and named reconciliation owners.
• Data classification that limits dashboard and cache models to the smallest permitted fields; tenant contact, payment, and balance data require separate encrypted stores and access controls.

Instructions

1. Build the contract-bound client and safe-read service layer first, with endpoint budgets, minimized cache entries, and observability before adding write or event processing.
2. Enable provider events only after the contract and durable raw-body, signature, persistence, and replay boundaries have been proven; otherwise use bounded incremental reconciliation.
3. Persist an idempotency/reconciliation record before any work-order, accounting, tenant, or lease mutation and require explicit authorization.
4. Validate the architecture in staging with synthetic data, a forced provider failure, duplicate event/retry, and rollback rehearsal before promotion.

Architecture Diagram

Dashboard (React) ──→ Property Service ──→ Redis Cache ──→ AppFolio Stack API
                           ↓                                 /properties
                      Queue (Bull) ──→ Sync Worker           /tenants
                           ↓                                 /leases
                      Event Handler ←── Provider events*      /work-orders
                           ↓                                 /bills
                      Accounting Sync ──→ QuickBooks/Xero

* Use provider events only when the active contract confirms their delivery and security semantics; otherwise feed the queue from bounded reconciliation.

Service Layer

class PropertyService {
  constructor(private client: AppFolioClient, private cache: CacheLayer) {}

  async getPortfolioSummary(propertyIds: string[]): Promise<PortfolioSummary> {
    const properties = await Promise.all(
      propertyIds.map(id => this.cache.getOrFetch(`prop:${id}`, () => this.client.get(`/properties/${id}`)))
    );
    return { totalUnits: properties.reduce((sum, p) => sum + p.units.length, 0),
             vacancyRate: this.calcVacancy…

AppFolio SDK Patterns

Overview

Production-ready patterns for the AppFolio property management REST API. AppFolio uses HTTP Basic Auth with client credentials and returns JSON responses for properties, tenants, leases, and work orders. A structured singleton client prevents credential sprawl, enforces consistent error handling, and centralizes pagination logic across all property management endpoints.

Prerequisites

• A provider-verified base URL, auth method, endpoint scope, and managed secret injection path for the target portfolio.
• Schema validation, request timeouts, endpoint-specific rate limits, and idempotency keys for all mutation-capable service methods.
• Synthetic fixtures for unit testing; production tenant, lease, and payment payloads must not become default mock, log, or error-message content.

Instructions

1. Construct one contract-bound client per runtime and reject missing or invalid configuration before requests begin.
2. Validate query bounds and response shapes at the service boundary, then pass only minimized typed fields to callers.
3. Return a classified 429 or unknown-write failure to the caller; retry only idempotent operations after the caller records the cursor/key and delay.
4. Keep write workflows behind explicit authorization, audit, and reconciliation controls rather than embedding them in generic SDK convenience helpers.

Singleton Client

import axios, { AxiosInstance } from 'axios';
let _client: AxiosInstance | null = null;
export function getClient(): AxiosInstance {
  if (!_client) {
    const clientId = process.env.APPFOLIO_CLIENT_ID;
    const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
    const baseURL = process.env.APPFOLIO_BASE_URL;
    if (!clientId || !clientSecret || !baseURL) throw new Error('APPFOLIO_CLIENT_ID, SECRET, and BASE_URL required');
    _client = axios.create({ baseURL, auth: { username: clientId, password: clientSecret }, timeout: 30000 });
  }
  return _client;
}

Error Wrapper

export class AppFolioError extends Error {
  constructor(public status: number, public code: string, message: string) { super(message); }
}
export async function safeCall<T>(operation: string, fn: () => Promise<T>): Promise<T> {
  try { return await fn(); }
  catch (err: any) {
    const status = err.response?.status ?? 0;
    if (status === 429) {
      const retryAfter = err.response?.headers?.['retry-after'];
      throw new AppFolioError(429, 'RATE_LIMIT', `Retry after ${retryAfter ?? 'provider-directed delay'}; do not replay an unknown write automatically`);
    }
    if (status === 401) throw new AppFolioError(401, 'AUTH', 'Invalid APPFOLIO_CLIENT_ID or SECRET');
    throw new AppFolioError(stat…

AppFolio Security Basics

Overview

AppFolio manages property portfolios containing tenant PII (SSNs, bank accounts, lease terms), owner financial data, and maintenance vendor records. A breach exposes rent rolls, payment histories, and personally identifiable tenant information across every managed property. Secure every integration point: API credentials, webhook endpoints, and any pipeline that touches tenant or owner financial records.

Prerequisites

• A verified AppFolio contract stating the permitted endpoint, authentication, webhook, data-retention, and portfolio-scoping requirements for the target environment.
• A secret manager, separate sandbox credentials, and a named security owner for rotations, access review, and incident response.
• A raw-body route configuration for any signed webhook: signature verification must run before JSON parsing, mutation, or logging of the request payload.

Instructions

1. Load credentials from the approved secret boundary, validate the HTTPS base URL, and give each worker only the scope it requires.
2. Receive webhook requests as bounded raw bytes, validate the signature shape and HMAC in constant time, then parse and schema-validate the payload.
3. Encrypt or minimize sensitive stored fields, redact nested PII before logs, and record access through a durable audit trail.
4. Run a rotation and webhook-negative-path rehearsal in sandbox; a failed signature, missing secret, or unverifiable endpoint is a no-go condition.

API Key Management

import https from "https";
import axios, { AxiosInstance } from "axios";

function createAppFolioClient(): AxiosInstance {
  const clientId = process.env.APPFOLIO_CLIENT_ID;
  const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
  const baseUrl = process.env.APPFOLIO_BASE_URL;
  if (!clientId || !clientSecret || !baseUrl) {
    throw new Error("Missing APPFOLIO_CLIENT_ID, APPFOLIO_CLIENT_SECRET, or APPFOLIO_BASE_URL");
  }
  return axios.create({
    baseURL: baseUrl,
    auth: { username: clientId, password: clientSecret },
    httpsAgent: new https.Agent({ minVersion: "TLSv1.2", rejectUnauthorized: true }),
  });
}

Webhook Signature Verification

import crypto from "crypto";

function verifyAppFolioWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-appfolio-signature"] as string;
  const secret = process.env.APPFOLIO_WEBHOOK_SECRET!;
  // req.body must be a bounded raw Buffer from the route's raw-body middleware.
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(req.body).digest("hex"));
  const received = signature ? Buffer.from(signature) : Buffer.alloc(0);
  if (received.length !== expected.l…

AppFolio Upgrade & Migration

Overview

AppFolio property management integrations depend on versioned REST API endpoints that evolve with the platform. Upgrades can rename fields on property and tenant objects, change pagination models, deprecate work-order endpoints, and alter the basic-auth flow. This skill detects your current API version, maps deprecated response shapes to replacements, and rolls back automatically if the new version fails.

Prerequisites

• Current API version prefix documented (e.g., /api/v1/)
• Access to the AppFolio API changelog and release notes
• Staging environment with test property and tenant data
• Client ID and secret stored in environment variables
• Existing integration test suite that covers core endpoints

Instructions

1. Run version detection to compare your active API version against the latest.
2. Review the AppFolio changelog for breaking changes between the two versions.
3. Apply schema migration transforms to property and tenant response objects.
4. Update endpoint URLs from the old version prefix to the new one.
5. Switch pagination from offset to cursor-based if required by the new version.
6. Run the smoke test suite against staging to verify all endpoints respond.
7. Deploy to production with the rollback strategy enabled.
8. Monitor error logs for 410/401 responses indicating missed migration steps.

Output

After a successful migration the skill produces:

• A VersionInfo object confirming current, latest, and deprecated versions
• Transformed property and tenant objects matching the new schema
• Smoke test results for properties, tenants, work orders, and accounting endpoints
• Rollback log entries if any endpoint fell back to the previous version

Version Detection

interface VersionInfo { current: string; latest: string; deprecated: string[]; }

async function detectApiVersion(baseUrl: string, headers: Record<string, string>): Promise<VersionInfo> {
  const res = await fetch(`${baseUrl}/api/status`, { headers });
  const body = await res.json();
  const current = res.headers.get("X-AppFolio-Api-Version") ?? body.api_version;
  const deprecated: string[] = body.deprecated_versions ?? [];
  if (deprecated.includes(current)) {
    console.warn(`Version ${current} is deprecated. Migrate to ${body.latest_version}.`);
  }
  return { current, latest: body.latest_version, deprecated };
}

Schema Migration

interface LegacyProperty { address_line1: string; unit_count: number; mgr_id: string; }
interface CurrentProperty { street_address: string; total_units: number; manager_id: string; }

function migrateProperty(old: LegacyProperty): CurrentProperty {
…

AppFolio Webhooks & Events

Overview

AppFolio Stack delivers real-time webhook notifications for property management lifecycle events including tenant onboarding, lease execution, rent payments, and maintenance workflows. Use these webhooks to sync AppFolio data with your CRM, accounting system, or custom property management dashboards without polling the API.

Prerequisites

• Written confirmation in the current AppFolio partner contract that the target portfolio supports the event types, registration process, delivery semantics, and signature scheme. Do not infer webhook support from another integration.
• A bounded raw-body ingress route, managed webhook secret, durable event store, queue, idempotency table, and owner for downstream accounting/CRM effects.
• A sandbox endpoint and synthetic events for valid, malformed, duplicate, and delayed-delivery tests before production registration.

Instructions

1. Register events only through the provider-issued process and contract-bound client after verifying the target URL, allowlist, and secret delivery path.
2. Verify bounded raw bytes and the signature before parsing; reject malformed or replayed events without logging tenant, payment, or lease content.
3. Persist the event ID, type, received time, and encrypted/minimized payload transactionally before acknowledging delivery, then process it asynchronously.
4. Enforce durable idempotency and reconcile unknown downstream outcomes before writing CRM, accounting, tenant, lease, or work-order state.

Webhook Registration

// Use this only if the signed provider contract explicitly supports this API.
const response = await createVerifiedAppFolioClient().post("/webhooks", {
    url: "https://yourapp.com/webhooks/appfolio",
    events: ["tenant.created", "work_order.updated", "payment.received", "lease.signed"],
    secret: process.env.APPFOLIO_WEBHOOK_SECRET,
});

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyAppFolioSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-appfolio-signature"] as string;
  const expected = Buffer.from(crypto
    .createHmac("sha256", process.env.APPFOLIO_WEBHOOK_SECRET!)
    .update(req.body)
    .digest("hex"));
  const received = signature ? Buffer.from(signature) : Buffer.alloc(0);
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  next();
}

Event Handler

import express from "express";
…