Skip to content
Vespy API

Security deposits and trust accounting

A security deposit is not revenue — it is the tenant’s money that you hold. Vespy tracks it in a trust subledger so the balance you hold per tenant can always be proved against the bank statement.

bank account ──> deposit ──> disposition (deduction | refund)
      └────────────> reconciliation

1. Set up a trust bank account

Section titled “1. Set up a trust bank account”

Deposits must be held separately from operating funds, so create the account once:

Terminal window
curl -X POST https://api.getvespy.com/api/trust/bank-accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Client Trust — Security Deposits",
    "accountType": "security_deposit",
    "institutionName": "First Republic",
    "accountMask": "4417"
  }'

accountType is operating, security_deposit, trust, or other. Store only the last few digits in accountMask — Vespy never holds full account numbers. Set ownerId if the account belongs to a single owner rather than the whole book.

2. Record the deposit

Section titled “2. Record the deposit”
Terminal window
curl -X POST https://api.getvespy.com/api/trust/deposits \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "leaseId": "'"$LEASE_ID"'",
    "tenantId": "'"$TENANT_ID"'",
    "bankAccountId": "'"$BANK_ACCOUNT_ID"'",
    "amountCents": 185000,
    "receivedAt": "2026-08-25T00:00:00Z"
  }'

This is a liability, not income. It never appears as revenue, and it stays on the subledger under the tenant’s name until it is disposed of.

3. Dispose of it at move-out

Section titled “3. Dispose of it at move-out”

A disposition is either a deduction (you keep some) or a refund (you return some). Record each one against the deposit:

Terminal window
curl -X POST "https://api.getvespy.com/api/trust/deposits/$DEPOSIT_ID/dispositions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "deduction",
    "amountCents": 42500,
    "reason": "Carpet replacement and repainting beyond normal wear",
    "lineItems": [
      { "description": "Carpet replacement — living room", "amountCents": 32000 },
      { "description": "Repaint bedroom wall", "amountCents": 10500 }
    ]
  }'

Fill in lineItems. Most jurisdictions require an itemized statement, and this is what GET /api/trust/deposits/{id}/deduction-statement renders into the PDF you send the tenant. Attach supporting evidence by uploading it as a document and passing documentId.

Then refund the remainder:

Terminal window
curl -X POST "https://api.getvespy.com/api/trust/deposits/$DEPOSIT_ID/dispositions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"type":"refund","amountCents":142500,"reason":"Balance returned at move-out"}'

4. Reconcile

Section titled “4. Reconcile”

Reconciliation proves that the cash in the account equals what the subledger says you owe:

Terminal window
curl -X POST https://api.getvespy.com/api/trust/reconciliations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "bankAccountId": "'"$BANK_ACCOUNT_ID"'",
    "periodStart": "2026-09-01",
    "periodEnd": "2026-09-30",
    "statementEndingBalanceCents": 4820000
  }'

The response reports the comparison against the ledger and the per-tenant subledger total. GET /api/trust/subledger-balances gives the same breakdown on demand, and GET /api/trust/ledger is the underlying entry list.

Owner payables

Section titled “Owner payables”

Money owed out to owners is the other side of trust accounting:

Terminal window
curl -X POST https://api.getvespy.com/api/trust/owner-payables \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ownerId":"'"$OWNER_ID"'","propertyId":"'"$PROPERTY_ID"'","amountCents":152000,"description":"September distribution"}'

Mark it paid with POST /api/trust/owner-payables/{id}/pay, or cancel it before payment with POST /api/trust/owner-payables/{id}/void.