Chapter 08API, Webhooks & Portals
4 min readAgency Client Inboxes & Scoped Lead Portal Architecture
Give agency clients dedicated inbox credentials (/client-portal) or Shared Inboxes access scoped strictly to their assigned websites and forms without exposing your master agency console.
Key Technical Takeaways (TL;DR)
- Create Client Inboxes in /client-inboxes by assigning a client email, agency-provided password, permission level, and scoped websites/forms.
- Attaching a Verified Website automatically grants the client inbox access to all forms linked to that website domain.
- Choose between Manage Leads (update Kanban stages, add notes, restore spam) or View-Only (read submissions, preview/download files, export CSV).
- Unified /login automatically routes unregistered client emails to /client-portal and supports multi-agency disambiguation or full account upgrades.
1. Configurable Permission Levels (Manage Leads vs View-Only)
Agencies control exactly what actions each client inbox can perform inside the Client Portal (/client-portal).
| Capability | Manage Leads (manage) | View-Only (view) | Agency Owner |
|---|---|---|---|
| View Scoped Submissions & Payload Fields | Allowed | Allowed | Allowed |
| Inline File Preview, Download & Drive Links | Allowed | Allowed | Allowed |
| Export Scoped Leads to CSV | Allowed | Allowed | Allowed |
| Move Leads Across Kanban Stages & Add Notes | Allowed | Read-Only | Allowed |
| Edit Form Schemas, API Keys, or Billing | Hidden / Blocked | Hidden / Blocked | Allowed |
2. Unified Login & Multi-Agency Identity Resolution
FormFork handles every client lifecycle scenario automatically so agencies never deal with credential collisions.
- Unregistered Client Email: Signing in at /login with the agency-provided email and password issues a scoped client_inbox JWT and redirects directly to /client-portal.
- Multiple Agencies Provisioning the Same Email: If two agencies assign different passwords to the same client email, FormFork matches the exact email + password pair. If both agencies set the exact same password, /login displays a workspace selector modal.
- Client Later Registers as a Full Admin Account: Registering at /register with the same email creates an independent full FormFork account without overwriting existing agency inboxes, and automatically surfaces all agency-assigned inboxes under the "Shared Inboxes" switcher.
Frequently Asked Technical Questions
Can a Client Inbox user see other clients or forms in my agency account?
No. The /api/client-portal/submissions endpoint strictly intersects requested forms with the inbox attachedFormIds and attachedWebsiteIds on the server.
What happens if my client later signs up for their own FormFork admin account?
Their new full account remains completely independent, and any client inboxes provisioned for their email address automatically appear under the "Shared Inboxes" tab in their dashboard.