Leases, maintenance and pipelines
هذه الصفحة بالإنجليزية عمدًا: أسماء الحقول والأوامر يجب أن تُقرأ تمامًا كما يعرضها المنتج وواجهة البرمجة.
The other lines of business follow the same pattern as the CRM sync: server keys with the line’s scopes, references for records, external ids for idempotent writes, webhooks with caused_by, and warnings instead of refusals for the company’s own business rules. People are references; their details come from GET /api/v1/contacts/{reference} with read:contacts.
Leases
Scopes read:leases and write:leases.
| Operation | Scope | What it does |
|---|---|---|
GET /api/v1/leases | read:leases | Leases: home, renter, term, rent, landlord, deposit, registration, notice, renewal, status |
POST /api/v1/leases | write:leases | Add a draft lease with its schedule (by number of payments, or the rows given) |
GET /api/v1/leases/{reference} | read:leases | One lease |
PATCH /api/v1/leases/{reference} | write:leases | A draft’s terms; registration, fee, handler, notes and your id at any time |
POST /api/v1/leases/{reference}/activate | write:leases | Draft to active (refused only over another active lease of the home) |
POST /api/v1/leases/{reference}/notice | write:leases | Record a notice: when, by whom, what it says |
POST /api/v1/leases/{reference}/renew | write:leases | The one renewal draft (sent again: the same one) |
POST /api/v1/leases/{reference}/end | write:leases | End an active lease, with the deposit’s outcome |
GET /api/v1/rent-payments | read:leases | Every payment, with the day it counted for the owner and its fee |
POST /api/v1/rent-payments | write:leases | A replacement for a bounced payment |
GET /api/v1/rent-payments/{payment_id} | read:leases | One payment |
PATCH /api/v1/rent-payments/{payment_id} | write:leases | Received, bounced, cancelled, or a change to a payment still due |
Warnings, not refusals. The company’s lease rules (notice periods, the rent increase cap, deposit percentages) come back as warnings codes on writes: schedule_total_differs, rent_above_cap, deposit_above_default, notice_late, vacate_notice_short. Show them to whoever decides; nothing is refused for them.
Cheques. A lease paid in post-dated cheques has one payment per cheque, with its number and bank. When a cheque clears, PATCH the payment with "status": "received"; when it bounces, "status": "bounced", then POST /api/v1/rent-payments with replaces for the new cheque. A bounced payment never changes again.
Accounting. A received payment carries booked_on (the day it counted for the owner’s statement) and fee_amount (the company’s fee then); a bounce after a receipt carries bounced_on, the day the reversal counted. These never change, so an export by booked_on month always gives the same totals. Subscribe to rent_payment.received, rent_payment.bounced and rent_payment.overdue, and to lease.created, lease.activated, lease.notice_given, lease.ended and lease.updated for the leases themselves.
Maintenance
Scopes read:maintenance and write:maintenance. Photos stay in the company’s own storage; the API gives their counts.
| Operation | Scope | What it does |
|---|---|---|
GET /api/v1/jobs | read:maintenance | Jobs: home, lease, category, priority, who does it, day, estimate, payer, owner’s approval, status |
POST /api/v1/jobs | write:maintenance | Add a job on a home (on its active lease when it has one) |
GET /api/v1/jobs/{reference} | read:maintenance | One job |
PATCH /api/v1/jobs/{reference} | write:maintenance | What is wrong, category, priority, payer, estimate, who does it, what was done, your id |
POST /api/v1/jobs/{reference}/schedule | write:maintenance | The day, the window, who does it; optionally block a holiday home’s calendar |
POST /api/v1/jobs/{reference}/complete | write:maintenance | The work is done |
POST /api/v1/jobs/{reference}/cancel | write:maintenance | The job will not happen |
POST /api/v1/jobs/{reference}/approval | write:maintenance | Ask the owner, record their answer, or go ahead without one |
GET /api/v1/job-charges | read:maintenance | What jobs cost, who pays, the day each counted for the owner |
POST /api/v1/job-charges | write:maintenance | Record a charge on a job |
GET /api/v1/job-charges/{charge_id} | read:maintenance | One charge |
PATCH /api/v1/job-charges/{charge_id} | write:maintenance | Cancel a charge (a mistake), or mark a renter’s charge paid |
GET /api/v1/contractors | read:maintenance | The firms the company gives work to |
POST /api/v1/contractors | write:maintenance | Add a contractor |
GET /api/v1/contractors/{contractor_id} | read:maintenance | One contractor |
PATCH /api/v1/contractors/{contractor_id} | write:maintenance | Change a contractor, or stop giving them work |
GET /api/v1/inspections | read:maintenance | Move-in, move-out and routine inspections with their areas |
POST /api/v1/inspections | write:maintenance | Plan an inspection (a lease’s move-in or move-out once) |
GET /api/v1/inspections/{reference} | read:maintenance | One inspection |
Warnings, not refusals. The owner’s approval never locks a job: approval_needed (the estimate is above the owner’s limit), not_approved (asked or declined, and the work goes on), calendar_taken (a stay covers the day, so the calendar was not blocked).
Helpdesk intake. POST /api/v1/jobs with external set to your ticket’s id: sent again, the same job comes back. Subscribe to job.scheduled, job.done and job.cancelled to update the ticket, and to job.approval_requested and job.approval_answered for the owner’s answer.
Accounting. A charge carries booked_on (the day it counted for the owner’s statement) and booked_owner; a cancellation carries cancelled_on. A charge never changes otherwise: a mistake is cancelled and recorded again. Subscribe to job_charge.booked and job_charge.cancelled.
Pipelines
Scopes read:pipelines and write:pipelines. The company manages its pipelines and stages on its screens; the API reads them and names stages by key.
| Operation | Scope | What it does |
|---|---|---|
GET /api/v1/pipelines | read:pipelines | The pipelines in their order, each with its stages: key, name, kind (open, won, lost), probability |
GET /api/v1/deals | read:pipelines | Deals: pipeline, stage, status, person, enquiry, home, handler, value, expected close, outcome |
POST /api/v1/deals | write:pipelines | Add a deal: from an enquiry’s reference, a person’s reference or their details |
GET /api/v1/deals/{reference} | read:pipelines | One deal |
PATCH /api/v1/deals/{reference} | write:pipelines | Title, home, owner, handler, department, money, probability, expected close, your id |
POST /api/v1/deals/{reference}/move | write:pipelines | To another stage by key, in any direction; a won or lost stage closes the deal |
GET /api/v1/viewings | read:pipelines | Viewings: deal, home, time, who shows it, how it went |
POST /api/v1/viewings | write:pipelines | Plan a viewing on a deal |
GET /api/v1/viewings/{reference} | read:pipelines | One viewing |
PATCH /api/v1/viewings/{reference} | write:pipelines | Change its time, home or who shows it, or record how it went |
Warnings, not refusals. A move never refuses for the company’s own rules: no_value, no_lease (a leasing deal won without its lease), no_lost_reason, reopened (a closed deal moved back to an open stage).
CRM sync. POST /api/v1/deals with external set to your deal’s id: sent again, the same deal comes back. Subscribe to deal.stage_changed (with deal.won and deal.lost for outcomes) and ignore the echo of your own writes by caused_by; moves made in the CRM come back with POST .../move and the stage’s key.
Website viewings. POST /api/v1/viewings with external set to your booking’s id. Subscribe to viewing.planned, viewing.updated, viewing.done, viewing.cancelled and viewing.missed; feedback never leaves the company in an event.