API and webhooks

Getting started

The API gives read-only JSON access to one business's records (included in the Pro and Enterprise plans). The owner or an admin makes a key under Settings → API keys; send it with every request:

curl "https://leasystream.com/api/v1/properties?limit=5" \
  -H "Authorization: Bearer lsapi_your_key_here"

• Base address: https://leasystream.com/api/v1. HTTPS only.
• The key goes in the Authorization: Bearer header and nowhere else. Cookies and keys in the address are ignored.
• A key reads the whole business: it is not limited to a person, branch or property. It cannot change anything.
• Amounts are numbers, and every record with money has a currency code next to them. Times are ISO 8601 in the business's timezone; dates are YYYY-MM-DD.
• GET https://leasystream.com/api/v1/me tells you which business a key belongs to, its currency and timezone.

Lists and pages

GET /{resource} returns up to limit records (default 50, most 100). Ask for the next page with page=2, or follow links.next until it is null:

{
  "data":  [ { … }, { … } ],
  "meta":  { "page": 1, "limit": 50, "has_more": true },
  "links": { "next": "/api/v1/properties?page=2&limit=50" }
}

GET /{resource}/{id} returns one record as {"data": { … }}. Filters go in the query string; a filter the resource does not have is ignored. Remember to URL-encode values (a + in a time must be sent as %2B).

Errors and limits

Errors look like {"error": {"code": "not_found", "message": "No record with that id."}}. Answers carry X-RateLimit-Limit and X-RateLimit-Remaining.

Resources

properties

Buildings and plots in the portfolio. GET /api/v1/properties and GET /api/v1/properties/{id}

Filters: q (name or code contains); status (active, inactive, under_construction, sold, archived); branch_id (a branch); updated_since (changed on or after this date or time).

units

Rentable units inside properties. GET /api/v1/units and GET /api/v1/units/{id}

Filters: property_id (a property); status (available, occupied, reserved, maintenance, off_market); updated_since (changed on or after this date or time).

renters

People and organisations who rent. GET /api/v1/renters and GET /api/v1/renters/{id}

Filters: q (name, email or phone contains); status (active, pending, suspended, blacklisted, archived); updated_since (changed on or after this date or time).

landlords

Property owners the business manages for. GET /api/v1/landlords and GET /api/v1/landlords/{id}

Filters: q (name, email or phone contains); status (active, pending, suspended, blacklisted, archived); updated_since (changed on or after this date or time).

leases

Leases, newest first. GET /api/v1/leases and GET /api/v1/leases/{id}

Filters: status (draft, active, expired, terminated, renewed); renter_id (a renter); landlord_id (a landlord); property_id (a property); unit_id (a unit); updated_since (changed on or after this date or time).

rent-charges

What is owed for each rent period, newest first. GET /api/v1/rent-charges and GET /api/v1/rent-charges/{id}

Filters: lease_id (a lease); status (pending, partial, paid, overdue, waived); from (due on or after); to (due on or before).

rent-payments

Rent received, newest first. GET /api/v1/rent-payments and GET /api/v1/rent-payments/{id}

Filters: lease_id (a lease); renter_id (a renter); status (recorded or voided); from (paid on or after); to (paid on or before).

payments

Other money received (deposits, application and reservation fees), newest first. GET /api/v1/payments and GET /api/v1/payments/{id}

Filters: purpose (application_fee, deposit_only, refund_received, reservation_fee, utility_deposit, other); status (recorded or voided); from (paid on or after); to (paid on or before).

expenses

Money spent, newest first. GET /api/v1/expenses and GET /api/v1/expenses/{id}

Filters: property_id (a property); vendor_id (a vendor); payment_status (paid, pending, voided); from (dated on or after); to (dated on or before).

disbursements

Payouts to landlords, newest first. GET /api/v1/disbursements and GET /api/v1/disbursements/{id}

Filters: landlord_id (a landlord); property_id (a property); status (draft, approved, paid, cancelled).

maintenance

Maintenance requests, newest first. GET /api/v1/maintenance and GET /api/v1/maintenance/{id}

Filters: property_id (a property); unit_id (a unit); status (pending, triaged, work_order_created, in_progress, completed, cancelled, duplicate); priority (emergency, high, medium, low).

branches

The business's offices. GET /api/v1/branches

Not available through the API or webhooks: staff accounts, internal notes and void reasons, national IDs and dates of birth, renters' employment details, landlords' bank details, and uploaded documents.

Webhooks

Webhooks (Growth, Pro and Enterprise plans) push events to your server instead of you asking. The owner or an admin adds an https address under Settings → Webhooks and picks the events. A POST with a JSON body arrives within about a minute:

POST /your/path HTTP/1.1
Content-Type: application/json
Leasystream-Event: lease.created
Leasystream-Delivery: evt_<number>
Leasystream-Signature: t=<unix time>,v1=<64 hex characters>

{
  "id": "evt_<number>",
  "type": "lease.created",
  "created_at": "<ISO 8601 time>",
  "business": { "id": <number>, "name": "<business name>" },
  "data": { … the record, in the same shape as the API returns it … }
}

• Answer with any 2xx status within 10 seconds; do slow work after answering.
• Otherwise it is tried again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, then marked failed. After 50 failures in a row the webhook is switched off.
• The same event can occasionally arrive twice, and events can arrive out of order: use id to ignore repeats.
• The address must be https with a valid certificate and must be on the public internet. Redirects are not followed.
• data shows the record as it was when the message was first sent; retries carry the same body.

Checking the signature

Leasystream-Signature holds a time (t) and v1, the HMAC-SHA256 of t + "." + the raw request body, keyed with the webhook's signing secret (whsec_…, shown once when the webhook is added or a new secret is made). Compute it yourself over the bytes exactly as received, compare in constant time, and refuse messages more than 5 minutes old.

// PHP
$body   = file_get_contents('php://input');
$secret = getenv('LEASYSTREAM_WEBHOOK_SECRET');           // whsec_…
$header = $_SERVER['HTTP_LEASYSTREAM_SIGNATURE'] ?? '';
$ok = preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)
   && abs(time() - (int) $m[1]) <= 300
   && hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);
if (!$ok) { http_response_code(400); exit; }
$event = json_decode($body, true);
http_response_code(200);

// Node.js (Express: use express.raw({ type: 'application/json' }) on this route,
// so req.body is the raw Buffer; header is req.get('Leasystream-Signature'))
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(m[1] + '.').update(rawBody).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], 'hex'));
}

Events

renter.updated and landlord.updated are combined when a record changes several times before the message goes out. A rent_payment.received message includes allocations, the rent charges the payment was applied to.