Add or edit client contacts

Who does this: Platform Admin · Payroll Lead · Payroll Executive When: Onboarding a new client, when a client tells you their submitter or approver has changed, or when a contact has left the company Result: The client's contact list reflects who can submit data and who can approve payroll. Future cycle emails go to the right people.

Every payroll client needs at least one submitter (someone the platform can email to ask for monthly changes) and at least one approver (someone who signs off on the prepared payroll before it's finalized). The same person can hold both capabilities — common for small clients where one operations manager handles everything.

This runbook covers the day-to-day case: adding a fresh contact, editing one, deactivating someone who's left, and the rare permanent-delete path.

Before you start

• [ ] You know the contact's full name (as they want it to appear on emails) and their work email. Personal emails are accepted but discouraged — they survive job changes.
• [ ] You know which capabilities they should hold:
  • Can submit intake — receives the monthly cycle-request email, opens the intake wizard, uploads documents.
  • Can approve payroll — receives the approval-request email after the export is generated, approves or requests revisions.
• [ ] If you're replacing a departing contact, you know whether to deactivate (preserves cycle history) or permanently delete (only works if they have no history).

WARNING

Email is the contact's primary identifier. Two contacts with the same email on the same client are not allowed. If you're changing someone's email because they got married or moved companies, edit the existing contact rather than creating a new one — otherwise their cycle history won't follow them.

Steps

To add a contact

1. Open Clients in the staff dashboard sidebar and click into your client.
2. On the client detail page, open the Contacts tab (or click Manage contacts on the Setup health panel if the client is freshly created).
3. Click Add contact, top-right of the contacts table.
4. Fill the dialog:
   • Name — Jane Doe
   • Email — jane@walker-tan.example
   • Capabilities — tick Can submit intake, Can approve payroll, or both. (At least one is required; the dialog enforces this.)
5. Click Add contact.

The new contact appears at the bottom of the contacts table, status Active.

To edit a contact

1. On the contacts table, click the edit (pencil) icon on the row.
2. Change name, email, or capabilities.
3. Click Save.

To deactivate a contact (the safe default)

1. On the contacts table, click the toggle on the row's Active column, or click the trash icon and choose Deactivate in the dialog.
2. Confirm.

Deactivation is reversible — re-toggle the row to bring them back. While deactivated, the contact:

• Receives no further emails (cycle requests, reminders, approvals).
• Stays visible in the contacts table greyed out.
• Remains attached to historical cycles (audit trail intact).

To permanently delete a contact

This is only available when the contact has no cycle history at all — no submissions, no approvals, no action requests received. The platform calculates this when you click the trash icon and shows you the breakdown.

1. Click the trash icon on the row.
2. Read the cycle-history preview. If any field is non-zero, only Deactivate will be available.
3. If permanent delete is allowed: type the contact's email exactly into the confirm field, then click Delete permanently.

WARNING

Permanent deletion is irreversible. For any contact who's been on at least one cycle, deactivate instead — Singapore record-retention rules require the audit trail.

How to know it worked

• The contact row appears (or updates) in the contacts table on the client detail page.
• The Activity log for the client shows contact.created, contact.updated, or contact.deactivated attributed to you.
• For a freshly added submitter on a client whose cycle has already started: the next cycle's request email will go to them. For a client mid-intake right now, the already-sent invitation does not retroactively reach them — use the cycle's Send invitation button to invite them on the open cycle.

What the client sees

Adding or editing a contact does not trigger any email by itself. The contact only starts hearing from the platform on the next cycle action that targets them:

• A new submitter gets the Payroll data request email when the next cycle initiates.
• A new approver gets the Payroll approval required email when the next export is generated.

Common situations

If you see…	It means…	What to do
Toast: "A contact with this email already exists for this client"	Same email is already on this client (active or deactivated)	If deactivated, reactivate them rather than creating a duplicate. If active, you're looking at the wrong client
Permanent delete is greyed out and only Deactivate is offered	The contact has cycle history (submissions, approvals, etc.)	Deactivate — the audit trail must be preserved
Email validation rejects the address	The address is malformed or missing the domain	Re-check; the platform requires name@domain.tld shape
You added a submitter mid-cycle but they didn't receive the cycle request	Cycle requests are sent at initiation; new contacts don't backfill	Open the cycle and click Send invitation to invite them on the live cycle
Approver was changed mid-cycle but the approval email went to the old person	Approval emails are auto-sent on Generate export; if the round is already open, the old recipient still holds the link	Open the cycle, use the manual Request approval flow to re-fire to the new approver

Related runbooks

• Create a new payroll client — the prerequisite step
• Start a payroll cycle — what happens to contacts when a cycle initiates
• Verify an email was sent — confirm a new contact actually received their first email
• Notifications catalog — every email a contact may receive
• RBAC matrix — which staff roles can manage contacts