The client portal
What clients (building owners and managing agents) see and do when they sign in to the portal, and what staff control about it. It is written for staff who explain the portal to clients and decide what to share, and for anyone supporting a client.
The portal is a separate area at /portal/*, branded with the company's name and logo. A
client sees only their own buildings, the projects on those buildings, open deadlines on their
buildings, the documents the company chose to share, and the invoices the company has sent. A
client can do exactly two things: send a work order (ask for a job) and ask to add a
building. Staff decide both; nothing a client does changes a project or a building directly.
Before you start
- The building must belong to the client. A client's portal shows the tracked buildings assigned to that client. Assign the client on the building page (violations, buildings and the map).
- Share documents deliberately. Nothing is visible to a client until a person with the manage-documents permission shares it (documents and filing).
- Mark invoices sent. A client sees an invoice only after it leaves Draft (proposals and invoices).
- Give people a login. Open the client, go to the Portal access tab and press Invite to portal (needs the manage-portal-access permission). See "Portal logins" below. A client signs in at the same address as staff, with the same login page, and lands on the portal dashboard.
What a client sees
The sidebar groups the pages as Overview (Home, Setting up, Map, Buildings), Compliance (Violations, Calendar) and Services (Requests & orders, Documents, Invoices), with Your company at the foot. Each section folds from its heading and is remembered in that browser; the one holding the open page never folds. Above the sections, Up next shows the next booked visit and how many work orders are waiting for review. On a phone a bar along the bottom holds Home, Buildings, Violations and Requests, and More opens the full menu. New work order is in the top bar of every page.
| Page | Address | What it shows |
|---|---|---|
| Home | /portal/dashboard | A one-line status (overdue deadlines and what is owed, or what is due soon, or "Nothing outstanding"), Waiting for your signature when a proposal was sent to sign, then Active projects, Pending work orders, Due in 30 days and Amount due; the active projects and the newest documents; and Coming up: everything dated in the next 7, 30 or 90 days, by day, with the overdue count and the next booked visit on top |
| Requests & orders | /portal/services | Two tabs. Requests (?tab=requests): the work orders the client sent, pending review first, and what became of each. Orders (?tab=orders): the client's projects as cards, Active, Completed or All (?show=), each with its next visit and progress. Counts of waiting requests, jobs in progress, the next visit and completed jobs sit on top; search covers addresses and services |
| Calendar | /portal/calendar | Open violations' correction and hearing dates, compliance obligations and booked visits on the client's buildings. Month (?view=month, the default on a computer) shows each day's items; picking a day lists them below, each deadline with Create work order. List (?view=list, the default on a phone) is the deadline list: Upcoming, Overdue, Waiting on the city (a hearing that has been held, or an HPD order certified and not yet accepted) and No fixed date, soonest first; counts follow the building filter and search. Overdue uses the same rule as the staff app (see below) |
| Buildings | /portal/buildings | The client's tracked buildings as cards or a table (the choice is remembered in that browser), with counts on top, Add a building, and the client's building requests |
| A building | /portal/buildings/:id | The building's borough, BIN, ZIP; its active projects, deadlines due in 30 days, overdue deadlines and open violations (each opening that list for the building); and its projects. Request work here opens a work order for the building |
| Violations | /portal/violations | The public record on the client's buildings: Lead paint (the default) or All violations; Open, Overdue and Closed tabs with Open, Overdue, Due in 30 days and Closed counts; each violation described in words with its deadline, most urgent first, and Create work order |
| A project | /portal/projects/:id | Origin, phase, phase sub-state and creation date, its Proposals (each sent to sign, waiting or signed), the project's shared documents and its sent invoices |
| Sign | /portal/sign/:id | One proposal sent to sign: the PDF, and a form to type a full name, tick the agreement and sign. Once signed, who signed and when, and the signed copy to download. The "please sign" email links here |
| Documents | /portal/documents | Every document shared with the client, searchable and filterable by building. A row leads to its project or building |
| Invoices | /portal/invoices | Invoices with status Sent, Paid or other, filterable |
Older addresses still work: /portal/work-orders opens Requests & orders on Requests,
/portal/projects opens it on Orders, and /portal/deadlines opens the Calendar's list, each
keeping anything after the ? (a building from the map, say).
Opening a document's View button mints a link that expires after about a minute, so a copied link stops working.
A violation is overdue in the portal exactly when it is overdue for staff, on the map and in My
Buildings (domain/src/violations/deadlineRule.ts): an open HPD order past its correct-by date in
New York, unless a certification of correction is on file and HPD hasn't rejected it. A hearing
date that has gone by (ECB/OATH, and OATH tickets filed under FDNY, Sanitation and Health) is
Hearing passed, never overdue. Every open dated record on the client's buildings is counted,
however many there are. Obligations count as overdue once their due date has passed.
The portal shows the project's phase as it is labeled on the staff side. Phase is set by hand and is not a promise of progress, so a project can show a phase that lags the work.
What a client can see of a document
A document appears in the portal only when all of these hold:
- a staff member shared it with that client;
- its status is past Draft (Issued, Signed or Notarized);
- it has not been voided;
- it is not a proposal or an invoice. The exception is the PDF of an invoice you sent, which is reachable from the client's invoices.
The other way in is sending a proposal to sign (proposals and invoices). Sending is not sharing: the client's portal shows that proposal, unsigned, and later its signed copy, until you withdraw the request. A withdrawn request, or one replaced because the proposal was regenerated or voided, takes it back out of the portal.
The portal lists only the newest version of each document. The client is recorded at the moment of sharing: if the building later moves to another client, the previous client keeps what was shared with them and the new client sees nothing until you share again. Stop sharing on the document withdraws it.
Branding
The portal uses the company's Branding settings: company name, logo and footer text. A client can carry an override, a display name, footer text and logo that replace the company's when that client signs in. Both are set under Settings → Branding (team and roles). The same client branding can also white-label that client's reports, so the reports it downloads carry its own logo and name.
The portal's colours are the same for every company and every client: the app's own palette, in light or dark as the person chooses. The Primary color and Secondary color settings colour generated PDFs only. What the company does choose is Client portal sidebar:
- Light (the default) suits a logo drawn in a dark colour or in colour.
- Black suits a logo that exists only in white. The sidebar is black in both light and dark, and on a phone the logo sits on a black tile in the top bar.
In dark mode the sidebar is black either way, and a light-sidebar logo sits on a white tile.
Work orders
A client sends a work order from New work order (top right of every portal page) or Request
this on a deadline: building, unit (optional), services, preferred dates, access notes and a
contact. Asked from a violation or a violation's deadline, the unit is the violation's apartment, or
the whole building for a records order (618–620), even one that names an apartment. The client follows it under Requests & orders → Requests. It arrives on the Work orders tab of Projects (/projects?tab=work-orders, needs
manage-work-orders; /work-orders still opens it) as New. The count beside Projects in the
sidebar, and on the tab, is how many are waiting. The list is grouped by client, then building,
newest first inside each; a folded group shows its orders by status.
- Accept opens a project for the client's building (origin "Client request") with one visit to schedule per service. The client sees the project straight away. When the work order came from a violation that is already in one of your open projects, it joins that project instead, adding a visit only for a service that project doesn't already have one scheduled for.
- A work order sent from a violation asks for that violation's apartment, or no apartment when the violation is for the whole building (no apartment, or a records order).
- Decline needs a reason; the client sees it.
- A client can cancel a work order until you decide it, and can send at most 10 a day.
Building requests
Add a building (/portal/buildings/add) asks one question at a time, the same questions as
Setting up's "Is any building missing?": which building (the register first, then NYC's address
search, or typing the address), how the client is connected to it, the super and anyone else on
site, its apartments, then a summary to send. Buildings already on the account or already asked
for can't be picked again. The request arrives in Buildings → ⋯ →
Client requests (needs manage-buildings). Approve tracks the building for that client and
fills any empty contacts; Decline needs a reason. Nothing a client types changes the city
building records.
Map and Your company
Map shows only the client's own buildings, framed to fit them. Each pin is coloured by what needs the client's attention (rose: overdue, with the count; amber: open but not overdue; grey: all clear), the list beside it is sorted most urgent first with Needs attention and Lead paint filters, and picking a building shows its overdue and open items, next deadline and next visit, with View building, See deadlines (the Calendar's list for that building), Street view and Request work. Street view opens the nearest street photo facing the building (Mapillary, within about 110 m; a building without one says so). It is offered from the client's own buildings only. It uses the same data as the client's other portal pages; it is not the staff map.
Your company shows what the client last sent in Setting up. See Client onboarding.
Setting up
Setting up walks a new client through ten steps, pre-filled from the city's records, and stages their answers for you on the client's page. See Client onboarding.
Notifications
Both sides get a bell (top right) with a red count. Staff hear about new work orders and building requests, and when a client signs a proposal (the person who sent it and the one who generated it); clients hear when one is decided, when a visit is booked, when a document or invoice is shared with them, and when a proposal is waiting for their signature. Clicking one opens the page it is about. A new one shows within a second or two, without refreshing or opening the bell.
Emails: portal invites, password resets, the decision emails to a client and the "please sign" email for a proposal are always sent. Emailing staff about new work orders and building requests is optional, under Settings → Client portal (off by default).
Portal logins
On a client's Portal access tab (each person's actions are in their row's ⋯ menu):
| Action | What it does |
|---|---|
| Invite to portal | Name, email, optional phone. The person gets an email with a link to set a password. A pop-up also shows the link with Copy link, for when the email doesn't arrive |
| Resend invite | A fresh link while the person is still Invited |
| Send password reset | For an Active login: a link to choose a new password |
| Turn off access | The person loses the portal at once and can't sign in; the login page tells them why. Turn on access reverses it. Logins are never deleted |
An invite link works once, and the copied link is the same link as the one in the email. If it has already been used (the person opened it before, or their email provider's link scanner did), the page says so and offers Email me a new link: they enter their email, get a link to choose a password, and the login turns Active once they set it. If they opened the link before in the same browser and never set a password, the page shows the password form instead of the error. Until a password is set, every page sends them back to that form.
Open a copied link in a private window, not the browser you're signed in to: the link signs that browser in as the person invited, replacing your own session.
One email address is one account: an address that already belongs to a staff member, or to another client's portal, can't be invited. Every login at a client sees the same things.
Not in the portal
A client cannot message the company, pay an invoice, or see a project's decisions, visit details, vendor payments or filing packages, or a proposal that was not sent to them to sign.
Preview as a client
An admin who can manage the team and view clients can open any of the firm's clients' portals as that client sees it: View as (top right, beside the bell) → Preview as client…, then a client. The portal opens on that client's dashboard with the firm's branding, and everything in it (buildings, violations, projects, documents, invoices) is exactly what that client's logins see, no more.
- A strip across the top reads Previewing
's portal · read-only · Exit ; Exit (or Exit preview in the account menu) returns to the client's page in the app. - It is read-only: New work order and every send or save button are off, and nothing is ever sent as the client. The bell is hidden (it would be yours).
- Each preview that starts is written to the firm's audit log (
portal_preview.start). - An operator viewing as the firm can preview its clients the same way.