Client Onboarding

Last verified against the codebase: 2026-07-27.

---

What it is

Client onboarding is the path from “we won the account” to “the client is working in their portal”: create the company, send the agreements for signature, invite their people, and confirm they arrived.

It has two halves. The onboarding tracker follows one client through seven steps, and the Getting Started checklist follows one workspace — yours or theirs — through the setup that makes the product useful. Both are progress surfaces; neither is a wizard you have to finish in one sitting.

---

Concepts

---

Roles and permissions

The role hierarchy is platform administrator > MSP administrator > MSP technician > organization administrator > power user > CUSTOMER`.

Note that MSP technician outranks organization administrator. Every rank floor below is “this role or higher” against that order.

Reading a tracker sits at MSP technician — the same floor as the client list and client detail pages — so a technician sees the same progress bars everyone else does. Writing one is MSP administrator, and the page hides the write controls from anyone below that rank rather than showing a button that fails.

Targeting another organization’s checklist is authorized against the servicing relationship: your account must be the client’s primary manager or hold an ACTIVE management link. An organization you do not service answers 404, not 403 — a 403 would confirm the identifier exists.

---

Walkthrough — onboarding a new client

MSP portal: Clients → Onboard Client. Six steps.

1. Company — name, subdomain slug, industry, size, website and address.
2. Primary contact — the person who will receive the welcome email, the documents and the portal invitation. Their email must not already exist.
3. Services — the managed services this client buys, with quantity and price. These become the contract lines.
4. Billing — cycle and contract length. A contract is created when services are selected.
5. Legal & Compliance — the documents to send. This step opens with your saved default document set already selected (Settings → Client Onboarding), and Require signing before portal access pre-set from the same place. You must accept the platform terms once before any documents can go out.
6. Review — confirm and create.

What happens on create, in one transaction: a client Account (managed by yours), an Organization, the contact Person with an organization administrator membership, the contract if any, the document package if any, and the onboarding tracker. A failure anywhere rolls all of it back — there is no half-created client.

After the transaction commits, emails go out:

• The client gets a welcome email, always.
• If documents were selected, the package is sent immediately to the primary contact with a signing link, and the tracker moves to AWAITING_SIGNATURES.
• If no documents were selected, the portal invitation goes out right away and the tracker sits at AWAITING_ACTIVATION.
• If documents were selected, the portal invitation is deliberately held back and released automatically when the package completes.

An email failure never rolls back the client. If the package could not be sent, it stays DRAFT and the client’s onboarding page offers Send documents.

---

Walkthrough — sending documents to an existing client

You can skip documents at onboarding time and send them later, or send a second package after the first completes.

1. Open Clients → client → Onboarding.
2. The No documents in flight panel offers Send documents.
3. Pick templates from your library, grouped by category.
4. Send to client. The package is created and delivered in one move, to the client’s primary contact, with the signer role from your onboarding defaults.

While a package is in flight the panel is replaced by the tracker’s own actions: Resend documents (rotates each unsigned signer’s link and emails it again) and Cancel package.

---

The onboarding tracker

Seven steps, in order:

The last three are derived, not written by the event: reading a tracker reconciles it against live portal state — magic links, verified emails, last login — and persists what it observes, with the real timestamp.

Reconciliation only ever moves steps forward. A step you ticked by hand is never un-ticked.

Overall status is one of six values and follows the steps:

Actions on the page reflect what is actually possible right now, not the status label: Send documents (a DRAFT exists), Resend documents (one is in flight), Cancel package, Send/Resend invitation (nobody has activated yet), Mark setup complete / Reopen onboarding. MSP administrator also gets a per-step Mark done / Mark not done override on every one of the seven steps, and the Notes field.

---

The onboarding pipeline

MSP portal: Clients → Onboarding pipeline (/msp/clients/onboarding).

Every client currently being onboarded, one row each: name, primary contact, a progress bar, the step they are waiting on, the stage badge and when it last moved. Filter by stage — including Stalled, which is what the reminder engine writes when a client stops responding — or search by client name. Clicking a row opens that client’s onboarding page.

---

Getting Started hubs

Two hubs, one component, one engine:

• MSP portal → Getting Started (/msp/getting-started) — 40 items in 6 groups: Company foundation, Your team, Service desk, Clients, Billing & finance, Operations & growth.
• Organization portal → Getting Started (/org/getting-started) — 34 items in 6 groups: Workspace foundation, Your team, Service desk & knowledge, Billing & subscription, Power features, Operations.

Each item carries a one-line summary, why it matters, what you will need, an estimated time, and a Set it up deep link into the page that does it. Three items (invite-team, queues, email-to-ticket) additionally offer Show me, a guided in-app tour of the target page — offered only in the portal the tour was written for.

Item states:

applicable = total − locked − skipped, and the percentage is round(100 × completed / applicable), or 100 when nothing applies.

Dismissing the checklist hides the nav entry, its progress pill and the dashboard card, and stops nudges. The hub itself stays reachable from Settings, and offers Restore it.

For a managed client

Three items are provider-owned on a managed client’s own hub and render as read-only “Handled by your provider”: sender identity, payment method, and invoice & billing settings. Everything else — including the plan, branding, custom domain, SSO and claiming an email domain — stays self-serve, because a managed client can upgrade its own plan.

The MSP’s view of a client’s hub

Open Clients → client → Onboarding. Below the tracker, the client’s own checklist appears with a group only you can see: Onboard this client, with four items — send onboarding documents, invite their portal users, confirm the client is in, and set up their service contract. Their overall completion percentage is shown underneath. On that view the three provider-owned items stop being read-only, because you are the provider.

---

Nudges and reminders

Three separate mechanisms, easy to confuse:

Signing reminders (per document package)

For each package that is SENT and not complete, timed by your Reminder cadence setting (default “every 5 days”):

• day N — a gentle reminder to the outstanding signer
• day 2N — a final reminder
• day 3N — no more email; the tracker is flagged STALLED

Exactly two emails per package. Each reminder rotates the signing token, so the link in the newest email is the only one that works.

If the package passes its expiry date first, it is retired to EXPIRED, the tracker is flagged STALLED, and its signing links stop opening.

Activation nudges (per workspace)

It scans up to 500 subjects per scope and emails each stalled one its single next step.

• Organizations — recipient is the primary active organization administrator; the link goes to /org/getting-started.
• MSP partner accounts — recipient is the primary active MSP administrator in the MSP’s own organization; the link goes to /msp/getting-started. An MSP’s own organization is excluded from the organization scan so it is never nudged about the wrong checklist.

A subject is skipped for a named reason: dismissed, complete, capped, too_soon, no_recipient, opted_out, no_next_step or send_failed. Cadence: at most 3 nudges ever, at least 3 days apart. The next step is always the first incomplete item, so a locked or provider-owned item is never the thing you are chased about. A failed send does not advance the cadence — it retries on the next run.

{ dryRun: true } runs the identical scan, sends nothing, writes no state and echoes the flag back; the job fails loudly if that echo is missing.

Activation snapshots

Runs daily at 02:00 UTC, on by default (analytics rows only, no email).

---

Every client-onboarding setting

MSP portal: Settings → Client Onboarding (/msp/settings/onboarding).

Never still bounds a signing token at 365 days. A bearer link that lives forever is a security hole, not a setting.

Two settings are per-package rather than per-account and override the defaults: an explicit expiresInDays when creating a package, and an explicit signers list when sending one.

---

Plan tiers

Client onboarding itself carries no plan gate. The tracker, the pipeline, the document packages, the signing flow, the portal invitation, both Getting Started hubs, the nudges and the snapshots are available on every tier including Free.

What is gated are individual items inside the checklists, which is exactly what the locked state exists to show:

A locked item shows the tier that unlocks it, its monthly price, and — when your account can self-serve — an Upgrade button that runs the prorated upgrade in place. Trying to tick a locked item through the API returns the same upgrade envelope rather than silently succeeding.

---

Activation reporting

Platform portal: Activation (/platform/activation). Built from the daily snapshots, per scope:

• total subjects, how many are fully activated, how many dismissed
• a distribution across five completion bands (0–25%, 26–50%, 51–75%, 76–99%, 100%)
• per checklist item, in configuration order: how many subjects it applied to, how many completed it, and the completion rate — the “where they stall” view

Items only the servicing MSP sees are excluded: the funnel measures activation, not the MSP’s per-client work.

---

Troubleshooting

“At least one signer is required — this client has no contact with an email address” You sent a package with no signers and the client organization has no active member with an email. Add a contact to the client, or name a signer explicitly.

“One or more signers are not members of this account” A signer you named is not in your account or in any account you service. Signer identity is validated against your servicing relationships, so the client’s own contact is accepted, but a person from an unrelated tenant is not.

“organizationId does not belong to this account” The organization you are creating a package for is neither yours nor one you service. Check you are using the client’s organization id, not its account id.

“Package has already been sent” /send only moves a DRAFT. To chase an in-flight package use /resend.

“Can only resend for sent or partially signed packages” The package is DRAFT (use /send), or it is already COMPLETED, CANCELLED or EXPIRED.

“This item is completed automatically and cannot be marked done manually” The checklist item has a detector. Do the underlying thing and it completes on its next load. This is deliberate: hand-ticking a detected item would make the percentage a fiction.

“This item is managed by your provider.” A managed client tried to change a provider-owned checklist item. Only three items are: sender identity, payment method, and invoice & billing settings.

“Onboarding tracker” (404) No tracker exists for that organization. Trackers are created with the client; a client imported by another route (an accounting import, for instance) may not have one.

The client says they never got the documents. Check the package status on the client’s onboarding page. DRAFT means it was never sent — use Send documents. EXPIRED means it passed the expiry window; send a new package. In development, outbound mail is redirected to an allowlist, so a redirected message is not a bug.

The signing link says it is invalid. Signing tokens are single-use, expire on the account’s schedule, and are rotated by every reminder and resend — so only the newest email works. A cancelled or expired package rejects all its links regardless of the token’s own clock.

A step on the tracker is wrong. Open the client’s onboarding page as MSP administrator and use the per-step Mark done / Mark not done override. Reconciliation never reverses a manual override.

The Getting Started entry disappeared from the nav. It was dismissed. The hub is still linked from Settings, and the page offers Restore it.

Then check the run’s skip reasons — capped (3 already sent), too_soon (inside the 3-day gap), opted_out (the recipient disabled email notifications), or no_recipient (no active organization administrator / MSP administrator with an email).

---

Limits and known behaviour

• The tracker is one per organization. A client cannot have two concurrent onboardings.
• “Setup Complete” is a human judgement. Nothing infers it; an admin marks it, or it follows first login into ACTIVE.
• Reconciliation is organization-wide, not contact-specific. If any member of the client organization has logged in, First Login is complete — the tracker measures whether the client arrived, not whether a particular person did.
• Signing reminders stop after two emails per package, whatever the cadence. The cadence changes the timing, not the count.
• Nudges stop after three, ever. There is no reset; a workspace that ignores three nudges is not nudged again.
• The nudge job is opt-in and the snapshot job is not. One sends mail; the other writes analytics rows.
• Package expiry is enforced by the 6-hourly sweep, so an expired package can look SENT for up to 6 hours. Its signing links stop working immediately regardless, because the tokens carry their own expiry.
• The client’s Getting Started hub is a view, not a remote control. From the client’s onboarding page an MSP can tick manual items and see progress; the client’s own gated features still require the client’s plan.
• Checklist item keys are permanent. Renaming one would orphan stored manual completions and skips, and break the funnel’s history.
• Onboarding is web-only. The mobile app lists clients but has no tracker, checklist or document-signing surface.
• There is no bulk onboarding. Clients are created one at a time through the wizard or the API.