Add and onboard a client

This guide covers: creating a client record with the five-step wizard, sending the e-sign onboarding packet, and watching the onboarding status track to "ready" so payroll can run.

Create a client record

What it does: Walks through a five-step wizard that captures every piece of legal, address, pay-schedule, contact, and beneficial-owner info Payrollix needs before any filing or money-movement can happen.

Where: Dashboard → Clients (/clients) → click Add Client (top right). The wizard lives at /clients/new.

Steps:

1. From /clients click Add Client.
2. Step 1 — Company: enter Legal Name (required), DBA (optional — set this if customers know the company by a trade name; this becomes the display name in the app), EIN in XX-XXXXXXX format (masked as you type), and pick Entity Type from the dropdown (Sole Proprietorship · Partnership · LLC · S Corporation · C Corporation · Nonprofit). Click Next.
3. Step 2 — Addresses: type the physical street address — the Google autocomplete fills city/state/ZIP. This address is registered as the client's "Main Office" work location and drives state withholding and local-tax setup. Leave Same as physical address ticked unless mail goes to a different PO box. Click Next.
4. Step 3 — Pay & Contact: pick Pay Frequency (Weekly · Bi-weekly · Semi-monthly · Monthly). Optionally enter one real First pay period (Period Start · Period End · Check Date) — the gap between Period End and Check Date sets days-until-payday for every future cycle. Tick Enable Same-Day ACH if the client is paying the per-batch fee. Add Company Phone and Company Email, plus optional Contact Person for W-2 / Tax Forms name, phone, email. Click Next.
5. Step 4 — Representatives: click Add representative for each beneficial owner (>=25%) and control officer (CEO, CFO, COO, Director). Enter first/last name, DOB, SSN, residential address, and tick Beneficial owner (>=25%) with ownership % and/or Control officer. Required for Moov KYB later, but click Skip for now if you don't have all the data yet — they can be added from Banking on the client record.
6. Step 5 — Review: scan the read-only summary (Company · Addresses · Pay & contact · Representatives) and click Create Client.

Who: Accountants. SMB owners don't see this — their single client is created at signup.

Notes: The progress stepper at the top lets you click back to any completed step but can't jump forward — each step validates required fields before advancing. If a representative fails to save (e.g. SSN already in use elsewhere) the client itself still gets created — you'll see "Client created, but N representative(s) failed — add them in Banking."

Send the onboarding packet

What it does: Emails the client an e-sign bundle of Form 8655, per-state Reporting Agent POAs, the Master Services Agreement, and Moov acknowledgements. Once signed, Payrollix is your authorized reporting agent and the client's Moov account can be opened.

Where: Two options.

• Per-client: Clients → [the client] → Overview (/clients/[clientId]) → click Invite to client portal (this also kicks off the onboarding packet for clients that haven't started it).
• Bulk across all clients: Clients (/clients) → click Send onboarding packets (amber outline button at the top).

Steps (per-client):

1. Open the client and stay on Overview.
2. Click Invite to client portal in the top-right.
3. The Invite to Client Portal modal opens with the client's email pre-filled. Edit if needed.
4. Click Send. The modal flips to a success state with the setup_url displayed.
5. Click Copy link if you want to deliver the link out-of-band (Slack, SMS, etc.) — handy when the client's email is unreliable.
6. Close the modal.

Who: Accountants only.

Notes: The right-side chip on the client overview reflects state — green Portal active once the client has signed in, amber Invite pending while the invite is outstanding. To kill an active portal, click Disable (next to the resend button) and confirm.

Watch onboarding status to "ready"

What it does: Shows whether the client has completed the e-sign packet, Moov KYB, banking, and the rest of the setup checklist. Until everything is green, payroll runs are gated.

Where: Clients → [the client] → Overview (/clients/[clientId]).

Steps:

1. Open the client overview.
2. Read the Setup Checklist card. The percentage at the top right is the % of total steps done; the bar visualizes it. Each row is a deep-link to the page that completes the step.
3. Common rows: Sign onboarding packet · Connect bank account · Add employees · Set state withholding accounts · Configure pay schedule · Set work locations.
4. Click any unchecked row to land on the right page; complete the step there and come back. Completed rows show a green check and the row text strikes through.
5. When progress_percent === 100 the checklist card disappears and the four stat tiles (Active Employees, YTD Gross Pay, Pending Timesheets, Pending Filings) become the focus.

Who: Accountants. SMB owners see the same checklist for their own company.

Notes: The hard gate on payroll runs is the onboarding packet (client.signing_status == 'fully_signed') or client.ra_on_file=True. Other checklist items (employees, banking) are best-practice but won't block create_payroll_run with the 412 ONBOARDING_PACKET_NOT_SIGNED error — that one's reserved for the e-sign packet specifically.

---

Related: Add your first client and run your first payroll · Client settings & work locations · Your filing authorization · What you need to provide for tax filing.