Create a new payroll client

Who does this: Platform Admin · Payroll Lead When: A new client has signed up for payroll, or you're moving an existing client off another system onto Spade Result: A client record exists in the staff dashboard, ready to be configured with contacts, an export template, and document rules before the first cycle can run.

This is the very first step when onboarding any payroll client. After creating the shell record, you'll add at least one contact, upload an Infotech import template, and configure document rules — only then can a cycle be started for that client. This runbook only covers creating the shell.

If you're onboarding a client that also uses Spade for bookkeeping, create the shell here with payroll enabled and toggle bookkeeping on after — products are independent and configured separately.

Before you start

• [ ] You have the Platform Admin role, or Payroll Lead role with MANAGE_CLIENTS permission. (Payroll Executives cannot create clients — see the RBAC matrix.)
• [ ] You have the client's legal name as it should appear on every email and document.
• [ ] You've agreed an internal client code with your team (a short uppercase identifier — e.g. WTAN, PNCL, MASN).
• [ ] You know the client's timezone (for scheduling automated cycle initiation) and the schedule day of the month their cycle should fire.

TIP

Pick the client code carefully — it appears in URLs, audit logs, and exported workbook filenames. Renaming it later is supported but disruptive. Two-to-six uppercase letters is the convention.

Steps

1. Open Clients under Administration in the staff dashboard sidebar.
2. Top-right of the clients list, click New client.
3. Fill the Identity card:
   • Client code — your short uppercase identifier (e.g. WTAN for Walker & Tan Associates Pte Ltd).
   • Legal name — the full registered entity name. This is what appears on every client-facing email subject and the approval report.
   • Timezone — defaults to Asia/Singapore. Change this only if the client genuinely operates in another zone; cycles initiate at the client's local 09:00.
   • Default schedule day — the day of the month the monthly cycle request fires (1–31). Most Singapore clients sit between 18 and 25 depending on their cutoff.
4. Click Create client.

You'll be redirected to the client detail page. The Setup health panel at the top will show four red items — that's expected. The next runbooks fix each one.

How to know it worked

• The client appears in the Clients list with the code and legal name you entered.
• The client detail page loads at /dashboard/clients/{id}.
• The Activity log for the client shows a client.created event attributed to you with a timestamp.
• The Setup health panel shows the client cannot start a cycle yet — the red items list contacts, templates, document rules, and (for payroll-only) approver coverage.

NOTE

Creating a client does not send any email. Nothing happens externally until you start the first cycle.

Common situations

If you see…	It means…	What to do
New client button is missing or greyed out	Your role lacks MANAGE_CLIENTS (you're a Payroll Executive)	Ask a Payroll Lead or Platform Admin to create the shell, then take over configuration
Toast: "Client code already in use"	Another client (active or archived) already has that code	Pick a different code; codes are unique across the firm even after archival
Toast: "Legal name must be unique"	A client with this exact legal name exists already	Confirm whether this is a duplicate onboarding; if it's a genuinely separate entity, append the registration suffix to disambiguate
Timezone field rejects your value	The platform only accepts IANA timezone IDs (e.g. Asia/Singapore, Asia/Kuala_Lumpur)	Use the IANA name, not an abbreviation like SGT
Schedule day is set to 30 or 31	The cycle won't fire in February (and on some months)	Use 28 or earlier if the client's cutoff is end-of-month — the platform skips past month-end rather than firing on the 1st

Next runbooks

After creating the client shell, you'll typically work through these in order:

1. Add or edit client contacts — at minimum one submitter and one approver
2. Upload an Infotech import template (see the Infotech template runbook — coming soon)
3. Configure document rules per change type (coming soon)
4. Start a cycle — first month go-live

Related runbooks

• Add or edit client contacts
• Start a payroll cycle
• RBAC matrix — exactly which actions each role can take
• Payroll cycle status machine — what happens after the first cycle is initiated