Build your own ownership app on AtomOwn

{ "ok": true, "data": { "service": "atomown-api", "version": "v1",
  "ci": "4.7.4", "env": "production", "time": "2026-09-14T09:12:03+01:00" } }

{ "ok": true, "data": {
  "developer": { "id": 11, "name": "Acme Homes", "slug": "acme-homes" },
  "theme":     { "key": "theme-2", "name": "Editorial" },
  "branding":  { "primary": "#0F7A68", "logo": "https://…/logo.png", "app_name": "Acme Own" },
  "content":   { "about": "…", "contact": "…", "privacy": "…", "terms": "…" },
  "features":  ["wallet", "secondary_market", "installments", "referral", "atomcredit", "manual_funding", "email_verification_required"],
  "loans":     { "enabled": true, "bank_name": "First Trust Bank" },
  "fees": {
    "withdrawal":       { "model": "flat", "pct": 0, "flat": 10000, "min": null, "max": null },
    "transfer":         { "developer": { "model": "percentage", "pct": 1.0, "flat": 0 },
                          "network":   { "model": "percentage", "pct": 1.5, "flat": 0 } },
    "secondary_market": { "developer": { "model": "percentage", "pct": 2.0, "flat": 0 },
                          "network":   { "model": "percentage", "pct": 1.5, "flat": 0 } },
    "liquidation":      { "developer": { "model": "percentage", "pct": 5.0, "flat": 0 },
                          "network":   { "model": "percentage", "pct": 1.5, "flat": 0 } }
  }
} }
// fees.*.developer is null when the developer has not configured that fee.
// fees.*.network  is null when no atomafrica_transaction rule exists in charge_rules.
// Flat amounts are in kobo; percentages are a plain number (1.5 = 1.5%).

{ "ok": true, "data": { "properties": [{
  "id": 12, "name": "Palm Estate",
  "category": "residential", "sub_category": "residential",
  "property_category_id": 3,
  "location": "12 Admiralty Way, Lekki Phase 1", "state": "Lagos",
  "latitude": 6.4281, "longitude": 3.4219,
  "total_value": 10000000, "unit_type": "flat",
  "packets_per_unit": 100, "packet_price": 10000, "base_packet_price": 10000,
  "amount_per_unit": 1000000, "base_amount_per_unit": 1000000,
  "total_units": 10, "available_units": 6.2,
  "total_packets": 1000, "available_packets": 620,
  "has_returns": true, "listing_status": "active", "cover": null, "images": []
}] } }

curl "$API/api/v1/properties?state=Lagos&sub_category=residential" \
  -H "Authorization: Bearer $TOKEN"

const params = new URLSearchParams({ state: "Lagos", sub_category: "residential" });
const { data } = await fetch(`${API}/api/v1/properties?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": { "properties": [{ /* property shape — see Public listings */ }] } }

curl "$API/api/v1/property-categories" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/property-categories`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": { "categories": [
  { "id": 3, "name": "Properties", "is_default": true,  "position": 1 },
  { "id": 1, "name": "Phase 1",    "is_default": false, "position": 2 },
  { "id": 2, "name": "Phase 2",    "is_default": false, "position": 3 }
] } }

curl -X POST "$API/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"developer":"acme-homes","name":"Ada Okoro","email":"ada@example.com",
       "password":"secret123","pin":"246813"}'

await fetch(`${API}/api/v1/auth/register`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ developer: "acme-homes", name: "Ada Okoro",
    email: "ada@example.com", password: "secret123", pin: "246813" }),
});

{ "ok": true, "data": {
  "token": "ao_live_9f2c8b1e…",
  "user": { "id": 402, "type": "customer", "name": "Ada Okoro",
            "email": "ada@example.com", "developer_id": 11,
            "roles": ["customer"], "permissions": [] }
} }

{ "ok": true, "data": {
  "email_verification_required": true,
  "email": "ada@example.com"
} }
// No token is issued. A 6-digit OTP (60-min TTL) is emailed to the address.
// Redirect the user to your verification screen and call POST /auth/verify-email.

{ "ok": true, "data": { "token": "ao_live_9f2c8b1e…", "user": { "id": 402, "type": "customer", … } } }

{ "ok": false, "error": { "code": "email_not_verified",
  "message": "Please verify your email address before logging in.",
  "details": { "email": "ada@example.com" } } }

{ "ok": true, "data": {
  "token": "ao_live_9f2c8b1e…",
  "user": { "id": 402, "type": "customer", "name": "Ada Okoro",
            "email": "ada@example.com", "email_verified": true }
} }

{ "ok": true, "data": { "sent": true } }
// Always returns { sent: true } regardless of whether the email exists,
// to prevent address enumeration. On cooldown (60s) sent is still true.

{ "ok": true, "data": { "user": { "id": 402, "type": "customer", "name": "Ada Okoro",
  "email": "ada@example.com", "developer_id": 11, "roles": ["customer"], "permissions": [] } } }

{ "ok": true, "data": { "loggedOut": true } }

{ "ok": true, "data": { "wallet": { "balance": 152000.00, "currency": "NGN" } } }

{ "ok": true, "data": { "reference": "DEP-3461A1B3", "amount": 25000.00,
  "deposit_fee": 50.00, "credited": 24950.00, "balance": 177000.00 } }

curl -X POST "$API/api/v1/purchases" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"property_id":12,"amount":15000,"pin":"246813"}'

await fetch(`${API}/api/v1/purchases`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ property_id: 12, amount: 15000, pin: "246813" }),
}).then(r => r.json());

{ "ok": true, "data": { "reference": "PUR-0637A42D", "packets": 1.5,
  "packet_price": 10000.00, "ownership": "1.5 packets", "cost": 15000.00,
  "atomafrica_fee": 225.00, "property": "Palm Estate" } }

{ "ok": true, "data": { "holdings": [{
  "property": "Palm Estate", "unit_type": "flat", "packets_per_unit": 100,
  "packets": 120, "units": 1.2, "whole_units": 1, "remainder_packets": 20,
  "ownership": "1 Flat and 20 packets", "packet_price": 10000.00,
  "acquisition_value": 1200000.00, "current_value": 1200000.00
}] } }

{ "ok": true, "data": { "plan": {
  "id": 17, "property": "Palm Estate", "status": "active",
  "total_amount": 120000.00, "tenor": 6, "frequency": "monthly",
  "installment_amount": 20000.00, "locked_unit_price": 10000.00,
  "paid_count": 0, "next_due_at": "2026-11-08" } } }

{ "ok": true, "data": { "manual_funding_enabled": true,
  "accounts": [
    { "bank_name": "First Bank", "account_number": "3012345678",
      "account_name": "Acme Homes Ltd", "is_active": true }
  ] } }

{ "ok": true, "data": { "property": {
  "name": "Palm Estate", "location": "Lekki, Lagos", "status": "active",
  "encumbered": false, "encumbrance_note": null,
  "packets": [{ "ref": "PKT-00042", "status": "owned", "encumbered": false }]
} } }

{ "ok": true, "data": { "reference": "WD-7DD1C6B4", "status": "pending", "amount": 40000.00 } }

curl -X POST "$API/api/v1/bid-offers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"property_id":12,"message":"Looking to acquire more packets in Palm Estate."}'

const { data } = await fetch(`${API}/api/v1/bid-offers`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ property_id: 12, message: "Looking to acquire more packets in Palm Estate." }),
}).then(r => r.json());

{ "ok": true, "data": { "bid_offer": {
  "id": 3, "property_id": 12, "property_name": "Palm Estate",
  "status": "active", "recipient_count": 4
} } }

curl "$API/api/v1/terms/transfer" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/terms/transfer`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": { "terms": {
  "feature_key": "transfer",
  "title": "Transfer Terms & Conditions",
  "content": "By proceeding with this transfer, you acknowledge …",
  "version": 1
} } }

{ "ok": true, "data": { "documents": [{
  "id": 5, "label": "Certificate of Occupancy",
  "url": "https://…/uploads/properties/12/docs/coo.pdf",
  "original_name": "coo-masked.pdf", "mime_type": "application/pdf"
}] } }

{ "ok": true, "data": {
  "eligible": true,
  "product_type": "equity_release",
  "bank_name": "First Trust Bank",
  "interest_rate": 18.0,
  "tenor_range": { "min_months": 3, "max_months": 24 },
  "max_ltv_pct": 30.0,
  "portfolio_value": 2500000.00,
  "max_principal": 750000.00,
  "min_principal": 50000.00,
  "terms_summary": "18% p.a. reducing balance · 3–24 months"
} }

{ "ok": true, "data": { "eligible": false, "reason": "no_portfolio" } }
// reason: no_bank_linked | no_portfolio | active_facility_exists | kyc_required

curl -X POST "$API/api/v1/credit-requests" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"product_type":"equity_release","property_id":12,"tenor_months":12,"requested_principal":500000,"consent_method":"app_checkbox"}'

const { data } = await fetch(`${API}/api/v1/credit-requests`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    product_type: "equity_release", property_id: 12,
    tenor_months: 12, requested_principal: 500000, consent_method: "app_checkbox"
  }),
}).then(r => r.json());

{ "ok": true, "data": { "credit_request": {
  "id": 7, "status": "submitted", "product_type": "equity_release",
  "requested_principal": 500000.00, "tenor_months": 12,
  "expires_at": "2026-10-09T10:00:00", "created_at": "2026-10-02T10:00:00"
} } }

{ "ok": true, "data": {
  "credit_requests": [{
    "id": 7, "product_type": "equity_release", "status": "with_bank",
    "requested_principal": 500000.00, "tenor_months": 12,
    "expires_at": "2026-10-09T10:00:00", "created_at": "2026-10-02T10:00:00"
  }],
  "pagination": { "page": 1, "per": 15, "total": 1, "pages": 1 }
} }
// status lifecycle: submitted → consents_pending → with_bank → approved
//   → pending_signing → (facility created) | declined | cancelled | expired

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "cancelled" } } }

{ "ok": true, "data": {
  "signature": { "id": 22, "party": "customer", "signatory_name": "Ada Okoro",
    "method": "electronic", "signed_at": "2026-10-05T14:22:00" },
  "execution": null
} }
// execution: non-null (facility object) once all 3 parties have signed

{ "ok": true, "data": {
  "facilities": [{
    "id": 3, "product_type": "equity_release", "status": "active",
    "principal": 500000.00, "outstanding_principal": 450000.00,
    "interest_rate": 18.0, "tenor_months": 12, "monthly_installment": 45833.33,
    "repayment_day_of_month": 5, "loan_ends_at": "2027-09-15",
    "disbursed_at": "2026-09-15T09:00:00",
    "locked_packets": 4, "locked_percentage": 80.0
  }],
  "pagination": { "page": 1, "per": 15, "total": 1, "pages": 1 }
} }
// status: pending_disbursement | pending_allocation | active | in_arrears | enforcement | closed_repaid

{ "ok": true, "data": {
  "facility_id": 3, "principal": 500000.00, "total_interest": 90000.00,
  "repayments": [
    { "id": 11, "instalment_number": 1, "due_date": "2026-10-15",
      "expected_amount": 49166.67, "status": "cleared",
      "cleared_at": "2026-10-14T11:00:00" },
    { "id": 12, "instalment_number": 2, "due_date": "2026-11-15",
      "expected_amount": 49166.67, "status": "pending", "cleared_at": null }
  ]
} }

{ "ok": true, "data": {
  "notifications": [
    { "id": 55, "type": "facility_disbursed",
      "title": "Facility disbursed",
      "body": "Your AtomCredit facility of ₦500,000 has been disbursed.",
      "sent_at": "2026-09-15T09:05:00", "read_at": "2026-09-15T09:12:00" }
  ]
} }

{ "ok": true, "data": {
  "enforcement_cases": [{
    "id": 1, "facility_id": 3, "status": "cure_running",
    "opened_at": "2026-10-01T08:00:00",
    "cure_period_ends_at": "2026-10-22T08:00:00",
    "outstanding_at_notice": 98333.34
  }]
} }
// status: notice_served | cure_running | enforcement_notice | listed | offer_accepted | settled | allocated | closed

curl "$API/api/v1/admin/credit-requests?status=submitted" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/credit-requests?status=submitted`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "credit_requests": [{
    "id": 7, "product_type": "equity_release", "status": "submitted",
    "customer": { "id": 9, "name": "Ada Okoro", "kyc_status": "approved" },
    "requested_principal": 500000.00, "tenor_months": 12,
    "expires_at": "2026-10-09T10:00:00", "created_at": "2026-10-02T10:00:00"
  }],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

curl -X POST "$API/api/v1/admin/credit-requests/7/confirm" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"note":"KYC verified, holdings confirmed."}'

await fetch(`${API}/api/v1/admin/credit-requests/7/confirm`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ note: "KYC verified, holdings confirmed." }),
}).then(r => r.json());

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "consents_pending" } } }

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "with_bank" } } }

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "declined" } } }

{ "ok": true, "data": {
  "credit_request": { "id": 7, "status": "pending_signing" },
  "facility_created": true,
  "facility_id": 3
} }

{ "ok": true, "data": {
  "facilities": [{
    "id": 3, "product_type": "equity_release", "status": "active",
    "customer": { "id": 9, "name": "Ada Okoro" },
    "principal": 500000.00, "outstanding_principal": 450000.00,
    "interest_rate": 18.0, "tenor_months": 12,
    "disbursed_at": "2026-09-15T09:00:00", "loan_ends_at": "2027-09-15"
  }],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

{ "ok": true, "data": {
  "charges": [{
    "property_id": 12, "property_name": "Lekki Gardens Phase 1",
    "active_facilities": 3, "total_principal": 1500000.00,
    "locked_packets": 12
  }]
} }

{ "ok": true, "data": {
  "confirmations": [{
    "facility_id": 3, "customer_name": "Ada Okoro", "property_name": "Lekki Gardens Phase 1",
    "contribution_amount": 200000.00, "confirmed_at": "2026-09-14T10:00:00"
  }]
} }

{ "ok": true, "data": {
  "allocations": [{
    "facility_id": 3, "unit_id": 88, "unit_reference": "LG-B2-P14",
    "customer_name": "Ada Okoro", "property_name": "Lekki Gardens Phase 1",
    "allocated_at": "2026-09-15T08:30:00"
  }]
} }

curl "$API/api/v1/admin/customers?q=ada&kyc_status=approved" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/customers?q=ada`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "customers": [
    { "id": 9, "user_id": 14, "name": "Ada Okoro", "email": "ada@example.com",
      "phone": "08012345678", "kyc_status": "approved",
      "acquisition_channel": "app", "created_at": "2026-08-01T10:00:00" }
  ],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

curl -X POST "$API/api/v1/admin/customers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Ada Okoro","email":"ada@example.com","phone":"08012345678"}'

const { data } = await fetch(`${API}/api/v1/admin/customers`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ada Okoro", email: "ada@example.com", phone: "08012345678" }),
}).then(r => r.json());

{ "ok": true, "data": {
  "customer": { "id": 9, "name": "Ada Okoro", "email": "ada@example.com", "phone": "08012345678" },
  "temp_password": "7f3a9c12!84"
} }

curl "$API/api/v1/admin/wallet" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/wallet`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "balance": 480000.00,
  "entries": [
    { "direction": "credit", "amount": 500000.00, "balance_after": 480000.00,
      "description": "Developer wallet top-up (DEV-DEP-7A3F)", "at": "2026-09-01T09:00:00" }
  ]
} }

curl -X POST "$API/api/v1/admin/wallet/topup" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":500000,"pin":"123456"}'

const { data } = await fetch(`${API}/api/v1/admin/wallet/topup`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 500000, pin: "123456" }),
}).then(r => r.json());

{ "ok": true, "data": {
  "reference": "DEV-DEP-7A3F2C1B",
  "balance": 480000.00,
  "deposit_fee": 2500.00
} }

curl -X POST "$API/api/v1/admin/wallet/withdraw" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":100000,"pin":"123456"}'

const { data } = await fetch(`${API}/api/v1/admin/wallet/withdraw`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 100000, pin: "123456" }),
}).then(r => r.json());

{ "ok": true, "data": { "reference": "DEV-WD-B4C1A902", "status": "pending" } }

{ "ok": true, "data": {
  "team": [{
    "id": 5, "name": "Emeka Obi", "email": "emeka@corp.com", "phone": "+2348012345678",
    "type": "staff", "status": "active",
    "role": "Accounting", "role_id": 3,
    "created_at": "2026-10-01T08:00:00"
  }],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

curl -X POST "$API/api/v1/admin/staff" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Emeka Obi","email":"emeka@corp.com","type":"staff","role_id":3}'

const { data } = await fetch(`${API}/api/v1/admin/staff`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Emeka Obi", email: "emeka@corp.com", type: "staff", role_id: 3 }),
}).then(r => r.json());

{ "ok": true, "data": {
  "user": { "id": 5, "name": "Emeka Obi", "email": "emeka@corp.com", "type": "staff" },
  "temp_password": "a3f8b2!47",
  "temp_pin": "293847"
} }

curl -X PATCH "$API/api/v1/admin/staff/5/role" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"role_id":4}'

await fetch(`${API}/api/v1/admin/staff/5/role`, {
  method: "PATCH",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ role_id: 4 }),
}).then(r => r.json());

{ "ok": true, "data": { "assigned": true, "role": "Finance", "role_id": 4 } }

curl -X POST "$API/api/v1/admin/commissions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"recipient_id":5,"recipient_type":"staff","amount":50000,"kind":"salary"}'

await fetch(`${API}/api/v1/admin/commissions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ recipient_id: 5, recipient_type: "staff", amount: 50000, kind: "salary" }),
}).then(r => r.json());

{ "ok": true, "data": { "reference": "SAL-8A3F1C…", "amount": 50000.00,
  "to": "staff", "recipient": "Emeka Obi", "kind": "salary" } }

{ "ok": true, "data": {
  "name": "Emeka Obi", "balance": 150000.00,
  "payments": [
    { "reference": "COMM-8A3F…", "kind": "salary", "amount": 50000.00, "created_at": "2026-10-01" }
  ]
} }

{ "ok": true, "data": {
  "roles": [
    { "id": 1, "key": "developer_admin", "name": "Developer Admin", "is_system": true,
      "permissions": ["properties.manage","customers.view","staff.manage","…"] },
    { "id": 3, "key": "custom_13_accounting", "name": "Accounting", "is_system": false,
      "permissions": ["earnings.view","reports.view"] }
  ]
} }

{ "ok": true, "data": {
  "permissions": [
    { "id": 4, "key": "earnings.view", "description": "View own earnings and commission history" },
    { "id": 7, "key": "properties.manage", "description": "Create and update property listings" }
  ]
} }

curl -X POST "$API/api/v1/admin/roles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Accounting","permission_ids":[4,7]}'

const { data } = await fetch(`${API}/api/v1/admin/roles`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Accounting", permission_ids: [4, 7] }),
}).then(r => r.json());

{ "ok": true, "data": { "id": 3, "key": "custom_13_accounting", "name": "Accounting" } }

{ "ok": true, "data": {
  "global_rate": 2.5,
  "rules": [
    { "property_id": 12, "property_name": "Sunset Estate", "rate_percent": 4.0 }
  ]
} }

# Global rate
curl -X POST "$API/api/v1/admin/agent-commission" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rate_percent":2.5}'

# Property override
curl -X POST "$API/api/v1/admin/agent-commission" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rate_percent":4.0,"property_id":12}'

# Remove property override (reverts to global rate)
curl -X POST "$API/api/v1/admin/agent-commission" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"rate_percent":null,"property_id":12}'

// Set global rate
await fetch(`${API}/api/v1/admin/agent-commission`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ rate_percent: 2.5 }),
}).then(r => r.json());

// Property override
await fetch(`${API}/api/v1/admin/agent-commission`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ rate_percent: 4.0, property_id: 12 }),
}).then(r => r.json());

// Remove property override → falls back to global rate
await fetch(`${API}/api/v1/admin/agent-commission`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ rate_percent: null, property_id: 12 }),
}).then(r => r.json());

{ "ok": true, "data": { "saved": true } }

{ "ok": true, "data": { "deleted": true } }

{ "ok": true, "data": {
  "attributed_customers": 14, "total_earned": 87500.00,
  "recent": [
    { "amount": 5000.00, "property": "Sunset Estate", "created_at": "2026-10-05" }
  ]
} }

{ "ok": true, "data": {
  "bank_account": { "bank_name": "Access Bank", "account_number": "0123456789", "account_name": "EMEKA OBI" }
} }

{ "ok": true, "data": { "reference": "SWR-F3A1C8…", "status": "pending", "amount": 50000.00 } }

{ "ok": true, "data": {
  "requests": [
    { "id": 2, "reference": "SWR-F3A1…", "amount": 50000.00,
      "status": "pending", "created_at": "2026-10-09T14:00:00" }
  ]
} }

{ "ok": true, "data": {
  "requests": [{
    "id": 2, "user_name": "Emeka Obi", "user_type": "staff",
    "amount": 50000.00, "bank_name": "Access Bank",
    "account_number": "0123456789", "account_name": "EMEKA OBI",
    "status": "pending", "created_at": "2026-10-09T14:00:00"
  }]
} }

{ "ok": true, "data": { "approved": true, "reference": "SWR-F3A1…" } }

{ "ok": true, "data": { "partners": [{
  "id": 3, "name": "PayFast NG", "contact_email": "dev@payfast.ng",
  "status": "active", "funding_model": "trust",
  "commission_rate": 2.5, "commission_trigger": "purchase",
  "reconciliation_balance": 125000.00,
  "customer_count": 18, "total_commission": 37500.00,
  "created_at": "2026-10-01T09:00:00"
}] } }

{ "ok": true, "data": {
  "partner": { "id": 3, "name": "PayFast NG", "status": "active",
               "funding_model": "trust", "commission_rate": 2.5 },
  "api_key": "pk_live_4f8c2b1d…",
  "portal_email": "dev@payfast.ng",
  "portal_password": "a3f9c1e0b2d5f8a4"
} }

{ "ok": true, "data": { "api_key": "pk_live_9c3e1a2f…" } }

{ "ok": true, "data": {
  "reconciled_naira": 125000.00,
  "message": "Reconciliation complete. Balance reset to ₦0."
} }

curl "$API/api/v1/admin/bid-offers?status=active" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/bid-offers?status=active`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "bid_offers": [{
    "id": 3, "property_id": 12, "property_name": "Palm Estate",
    "customer_id": 42, "customer_name": "Ada Okoro",
    "message": "Looking to acquire more packets.",
    "status": "active", "created_at": "2026-10-13 09:14:00"
  }],
  "count": 1,
  "pagination": { "page": 1, "per": 25, "total": 1, "pages": 1 }
} }

curl "$API/api/v1/admin/terms" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/terms`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "terms": [{
    "feature_key": "transfer", "title": "Transfer Terms & Conditions",
    "content": "By proceeding with this transfer …",
    "version": 1, "is_custom": false, "updated_at": null
  }, { "feature_key": "bid_offer", … }, { "feature_key": "secondary_market", … },
     { "feature_key": "property_listing", … }, { "feature_key": "installment_plan", … },
     { "feature_key": "buy_packets", … }],
  "variables": [{ "name": "{{developer_name}}", "description": "Your company name as set in branding settings" }]
} }

curl -X POST "$API/api/v1/admin/properties/12/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "label=Certificate of Occupancy" \
  -F "document=@/path/to/coo-masked.pdf"

const fd = new FormData();
fd.append("label", "Certificate of Occupancy");
fd.append("document", fileInput.files[0]);
await fetch(`${API}/api/v1/admin/properties/12/documents`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: fd,
}).then(r => r.json());

{ "ok": true, "data": { "document": {
  "id": 5, "label": "Certificate of Occupancy",
  "url": "https://…/uploads/properties/12/docs/coo-masked.pdf",
  "original_name": "coo-masked.pdf", "file_size": 204800,
  "mime_type": "application/pdf", "created_at": "2026-10-13T10:00:00"
} } }

curl "$API/api/v1/admin/property-categories" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "$API/api/v1/admin/property-categories" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Phase 2"}'

curl -X PATCH "$API/api/v1/admin/property-categories/3" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Residential"}'

// List
const { data } = await fetch(`${API}/api/v1/admin/property-categories`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

// Create
await fetch(`${API}/api/v1/admin/property-categories`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Phase 2" }),
}).then(r => r.json());

{ "ok": true, "data": { "categories": [
  { "id": 3, "name": "Properties", "is_default": true,  "position": 1 },
  { "id": 1, "name": "Phase 1",    "is_default": false, "position": 2 }
] } }

{ "ok": true, "data": { "category": { "id": 2, "name": "Phase 2", "is_default": false, "position": 2 } } }

curl -X POST "$API/api/v1/admin/properties/12/allocate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"customer_email":"ada@example.com","plot_number":"A12","unit_fraction":1.0}'

const { data } = await fetch(`${API}/api/v1/admin/properties/12/allocate`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ customer_email: "ada@example.com", plot_number: "A12", unit_fraction: 1.0 }),
}).then(r => r.json());

{ "ok": true, "data": { "allocation": {
  "id": 1, "property_id": 12, "plot_number": "A12",
  "unit_fraction": 1.0, "total_packets": 100, "status": "active",
  "shares": [{ "customer_id": 42, "customer_name": "Ada Okoro", "packets": 100 }]
} } }

curl -X POST "$API/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"emeka@firsttrustbank.ng","password":"BkA3F8c1!"}'

const { data } = await fetch(`${API}/api/v1/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "emeka@firsttrustbank.ng", password: "BkA3F8c1!" }),
}).then(r => r.json());
const token = data.token;

{ "ok": true, "data": { "token": "ao_live_7e4a…", "user": { "id": 7, "type": "bank_admin",
  "name": "Emeka Obi", "email": "emeka@firsttrustbank.ng", "bank_id": 1 } } }

{ "ok": true, "data": {
  "versions": [{
    "id": 2, "bank_id": 1, "version": 2,
    "effective_from": "2026-09-01", "effective_until": null,
    "interest_rate": "18.0000",
    "tenor_options_months": "6,12,24,36",
    "advance_cap": "30.0000",
    "default_fee_pct": "5.0000",
    "net_realisation_factor": "0.8500",
    "cure_period_days": 30,
    "resale_period_days": 90,
    "settlement_period_days": 14,
    "listing_price_floor_factor": "0.7500",
    "release_step_pct": "1.0000",
    "request_lock_expiry_hours": 168,
    "allocation_window_hours": 72,
    "realisation_cost_fixed": 0,
    "created_by": 5, "created_at": "2026-09-01T08:00:00"
  }]
} }
// tenor_options_months: comma-separated list of allowed tenor choices shown to customers
// advance_cap: max LTV % (e.g. "30.0000" = 30% of unit value)
// default_fee_pct: penalty % added to outstanding balance on enforcement notice
// net_realisation_factor: expected recovery fraction on forced sale (used in risk calc)
// release_step_pct: minimum % increment for progressive lock release after each repayment

curl -X POST "$API/api/v1/admin/bank/parameters" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "effective_from":"2026-10-01","interest_rate":"18.0000",
    "tenor_options_months":"6,12,24,36","advance_cap":"30.0000",
    "default_fee_pct":"5.0000","net_realisation_factor":"0.8500",
    "cure_period_days":30,"resale_period_days":90,"settlement_period_days":14,
    "listing_price_floor_factor":"0.7500","release_step_pct":"1.0000",
    "request_lock_expiry_hours":168,"allocation_window_hours":72,
    "realisation_cost_fixed":0
  }'

await fetch(`${API}/api/v1/admin/bank/parameters`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    effective_from: "2026-10-01", interest_rate: "18.0000",
    tenor_options_months: "6,12,24,36", advance_cap: "30.0000",
    default_fee_pct: "5.0000", net_realisation_factor: "0.8500",
    cure_period_days: 30, resale_period_days: 90, settlement_period_days: 14,
    listing_price_floor_factor: "0.7500", release_step_pct: "1.0000",
    request_lock_expiry_hours: 168, allocation_window_hours: 72,
    realisation_cost_fixed: 0,
  }),
}).then(r => r.json());

{ "ok": true, "data": { "version": { "id": 3, "version": 3,
  "effective_from": "2026-10-01", "interest_rate": "18.0000",
  "tenor_options_months": "6,12,24,36", "advance_cap": "30.0000",
  "created_by": 5, "created_at": "2026-10-01T08:00:00" } } }

{ "ok": true, "data": { "version": { "id": 3, "interest_rate": "18.0000", … }, "in_use": false } }
// in_use: true means non-effective_until fields were ignored (version is locked)

curl "$API/api/v1/admin/bank/credit-requests?status=with_bank" \
  -H "Authorization: Bearer $TOKEN"

const { data } = await fetch(`${API}/api/v1/admin/bank/credit-requests?status=with_bank`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.json());

{ "ok": true, "data": {
  "credit_requests": [{
    "id": 7, "product_type": "equity_release", "status": "with_bank",
    "requested_principal": 500000.00, "tenor_months": 12,
    "customer": { "name": "Ada Okoro", "kyc_status": "approved" },
    "created_at": "2026-10-02T10:00:00"
  }],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

{ "ok": true, "data": {
  "credit_request": { "id": 7, "status": "with_bank", "product_type": "equity_release",
    "requested_principal": 500000.00, "tenor_months": 12, "interest_rate": 18.0 },
  "customer": { "name": "Ada Okoro", "email": "ada@example.com",
    "kyc_status": "approved", "dob": "1990-03-15" },
  "holdings": [
    { "property": "Lekki Gardens Phase 1", "unit_type": "plot",
      "packets": 5, "current_value": 1250000.00,
      "free_packets": 5, "locked_packets": 0 }
  ],
  "live_portfolio_value": 1250000.00,
  "max_eligible_principal": 375000.00
} }

curl -X POST "$API/api/v1/admin/bank/credit-requests/7/approve" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"approved_principal":450000,"approved_tenor_months":12}'

await fetch(`${API}/api/v1/admin/bank/credit-requests/7/approve`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ approved_principal: 450000, approved_tenor_months: 12 }),
}).then(r => r.json());

{ "ok": true, "data": {
  "credit_request": { "id": 7, "status": "approved",
    "approved_principal": 450000.00, "approved_tenor_months": 12,
    "decided_by_user_id": 5, "decided_at": "2026-10-03T11:15:00" }
} }

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "declined",
  "decided_by_user_id": 5, "decided_at": "2026-10-03T11:20:00",
  "decision_reason": "Insufficient equity coverage." } } }

{ "ok": true, "data": { "credit_request": { "id": 7, "status": "info_requested" } } }

{ "ok": true, "data": {
  "credit_request": { "id": 7, "status": "pending_signing" },
  "message": "Bank signature recorded. Awaiting customer and developer signatures."
} }

{ "ok": true, "data": {
  "facilities": [{
    "id": 3, "product_type": "equity_release", "status": "active",
    "customer": { "id": 9, "name": "Ada Okoro" },
    "principal": 500000.00, "outstanding_principal": 450000.00,
    "interest_rate": 18.0, "tenor_months": 12, "repayment_day_of_month": 5,
    "monthly_installment": 45833.33, "loan_ends_at": "2027-09-15",
    "disbursed_at": "2026-09-15T09:00:00", "bank_reference": "BNK-2026-003"
  }],
  "pagination": { "page": 1, "per": 20, "total": 1, "pages": 1 }
} }

curl -X POST "$API/api/v1/admin/bank/facilities/3/disburse" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"repayment_day_of_month":5}'

await fetch(`${API}/api/v1/admin/bank/facilities/3/disburse`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ repayment_day_of_month: 5 }),
}).then(r => r.json());

{ "ok": true, "data": {
  "facility": { "id": 3, "status": "active", "disbursed_at": "2026-09-15T09:00:00" },
  "atomcredit_fee": 4500.00, "fee_rate_pct": 1.0
} }

{ "ok": true, "data": {
  "facility_id": 3, "principal": 450000.00,
  "repayments": [
    { "id": 11, "amount": 44250.00, "is_cleared": true,
      "cleared_at": "2026-10-04T14:00:00", "source": "manual",
      "bank_reference": "TRF-001", "idempotency_key": "REP-FAC3-OCT26",
      "required_lock_pct_after": 91.67, "released_pct": 8.33,
      "release_applied_at": "2026-10-04T14:01:00",
      "is_reversed": false, "reversed_at": null, "reversal_reason": null },
    { "id": 12, "amount": 44250.00, "is_cleared": false,
      "cleared_at": null, "source": "manual",
      "bank_reference": null, "idempotency_key": "REP-FAC3-NOV26",
      "required_lock_pct_after": 83.33, "released_pct": null,
      "release_applied_at": null, "is_reversed": false }
  ]
} }

{ "ok": true, "data": { "repayment": {
  "id": 13, "amount": 44250.00, "is_cleared": false,
  "idempotency_key": "REP-FAC3-NOV26", "bank_reference": null, "source": "manual"
} } }

{ "ok": true, "data": {
  "repayment": { "id": 12, "is_cleared": true, "cleared_at": "2026-11-04T15:00:00" },
  "release": {
    "required_lock_pct_after": 75.0,
    "released_pct": 8.33,
    "applied": true,
    "suspended": false
  }
} }

{ "ok": true, "data": { "repayment": { "id": 12, "status": "pending", "reversed": true } } }

{ "ok": true, "data": {
  "facility": { "id": 3, "status": "closed_repaid" },
  "lock_state": "released",
  "release_deed": {
    "doc_version_id": 2, "doc_ref": "deed-release-fac3",
    "content_hash": "abc123…", "document_path": "deeds/release/fac3.html"
  }
} }

{ "ok": true, "data": { "facility": { "id": 3, "status": "in_arrears" } } }

{ "ok": true, "data": { "facility": { "id": 3, "status": "active" } } }

{ "ok": true, "data": {
  "facility": { "id": 3 },
  "enforcement_case": { "id": 1, "status": "notice_served" }
} }

{ "ok": true, "data": {
  "enforcement_cases": [{
    "id": 1, "facility_id": 3, "status": "cure_running",
    "customer": { "name": "Ada Okoro" },
    "outstanding_at_notice": 88500.00, "default_fee": 4425.00,
    "enforcement_portion_pct": 80.0, "opened_at": "2026-10-01T08:00:00",
    "cure_period_ends_at": "2026-10-22T08:00:00"
  }],
  "count": 1
} }

{ "ok": true, "data": {
  "enforcement_case": { "id": 1, "status": "cure_running",
    "cure_period_ends_at": "2026-10-22T08:00:00" }
} }

{ "ok": true, "data": {
  "enforcement_case": { "id": 1, "status": "settled" },
  "facility": { "id": 3, "status": "active" }
} }

{ "ok": true, "data": { "enforcement_case": { "id": 1, "status": "enforcement_notice" } } }

{ "ok": true, "data": { "enforcement_case": { "id": 1, "status": "enforcement_notice" },
  "dispute_recorded": true } }

{ "ok": true, "data": {
  "wallet": { "balance": 4800000.00, "total_funded": 5000000.00, "total_withdrawn": 200000.00 },
  "statement": [
    { "id": 99,  "type": "credit", "amount": 5000000.00,
      "description": "Initial wallet credit", "created_at": "2026-09-01 09:00:00" },
    { "id": 101, "type": "debit",  "amount": 4500.00,
      "description": "AtomCredit fee: facility #3", "created_at": "2026-09-15 09:30:00" }
  ]
} }

{ "ok": true, "data": {
  "active_facilities": 12,
  "total_outstanding": 5400000.00,
  "equity_release": { "count": 8, "outstanding": 3600000.00 },
  "purchase_finance": { "count": 4, "outstanding": 1800000.00 },
  "total_repayments_cleared": 1200000.00,
  "total_atomcredit_fees": 54000.00
} }

{ "ok": true, "data": {
  "arrears": [{
    "facility_id": 3, "customer_name": "Ada Okoro", "status": "in_arrears",
    "principal": 450000.00, "arrears_amount": 88500.00,
    "missed_payments": 2, "last_cleared_at": "2026-09-04T14:00:00"
  }]
} }

{ "ok": true, "data": {
  "enforcement_cases": [{
    "id": 1, "facility_id": 3, "status": "cure_running",
    "customer_name": "Ada Okoro", "outstanding_at_notice": 88500.00,
    "cure_period_ends_at": "2026-10-22T08:00:00",
    "enforcement_portion_pct": 80.0
  }]
} }

{ "ok": true, "data": {
  "realisations": [{
    "enforcement_case_id": 1, "facility_id": 3, "customer_name": "Ada Okoro",
    "outstanding_at_enforcement": 350000.00,
    "proceeds_recovered": 380000.00, "residual": 30000.00,
    "resolved_at": "2026-11-10T10:00:00"
  }]
} }

{ "ok": true, "data": {
  "count": 2,
  "pagination": { "page": 1, "per": 25, "total": 2, "pages": 1 },
  "team": [
    { "id": 12, "name": "Zainab Musa", "email": "z.musa@bank.ng", "phone": null,
      "type": "staff", "status": "active", "role": "Loan Officer", "role_id": 8,
      "created_at": "2026-10-10T09:00:00" }
  ]
} }

{ "ok": true, "data": {
  "user": { "id": 12, "name": "Zainab Musa", "email": "z.musa@bank.ng", "type": "staff" },
  "temp_password": "4f8c2b1d!47",
  "temp_pin": "083142"
} }

{ "ok": true, "data": { "roles": [
  { "id": 2, "key": "staff", "name": "Staff", "is_system": true,
    "permissions": [] },
  { "id": 9, "key": "bank_1_loan_officer", "name": "Loan Officer",
    "is_system": false, "permissions": ["bank.loans.view","bank.loans.manage"] }
] } }

{ "ok": true, "data": { "permissions": [
  { "id": 18, "key": "bank.loans.view",      "description": "View loan applications" },
  { "id": 19, "key": "bank.loans.manage",    "description": "Review, approve and decline loans" },
  { "id": 20, "key": "bank.wallet.view",     "description": "View bank wallet balance and history" },
  { "id": 21, "key": "bank.wallet.move",     "description": "Fund and withdraw from bank wallet" },
  { "id": 22, "key": "bank.settings.manage", "description": "Manage bank LTV ratio and interest rate" },
  { "id": 23, "key": "bank.staff.manage",    "description": "Manage bank staff and roles" }
] } }

{ "ok": true, "data": { "id": 9, "key": "bank_1_loan_officer", "name": "Loan Officer" } }