Client Portal Requirements: How to Write Them

Most client portal projects that disappoint do not fail on technology. They fail because nobody wrote down, precisely enough, what clients need to do in the portal, what data they should see, which systems the data comes from and what "done" looks like. The result is a portal built on assumptions, followed by months of change requests. Good client portal requirements fix this before a line of code is written. This guide explains how to gather and write client portal requirements: who to involve, how to describe users and tasks, how to capture data, integration and security needs, how to prioritise and how to write acceptance criteria, with a worked example of a requirements set you can adapt.

Why client portal requirements matter

A client portal sits between your internal systems and your clients. That makes its requirements unusually broad: every screen depends on data from a CRM, accounting or project system; every client sees only their own information; and the people who will use it most, your clients, are rarely in the room when it is specified. Gaps show up late and expensively, often as "we assumed the portal would also do this".

Clear requirements also make quotes comparable. Two suppliers pricing a vague brief will price different products; two suppliers pricing the same detailed requirements can be compared fairly.

Who to involve

• Client-facing staff, such as account managers and support, who know what clients ask for
• Finance, if invoices, statements or payments are in scope
• Operations or delivery teams, who own project, order or case data
• IT or systems owners, who know where data lives and what integrations are possible
• A few friendly clients, interviewed or shown early sketches

Ask client-facing staff for the ten most common questions clients send by email or phone. Those questions are usually the best starting list of portal features.

Describe users and their tasks

Start with who will use the portal and what they need to achieve, not with screens. Typical user types include the client's main contact, other client staff with limited access, a client finance contact who handles invoices, and your own staff who support clients through the portal.

Write tasks as short user stories: "As a client finance contact, I want to download any invoice from the last two years, so I can reconcile our accounts without emailing you." Each story names a user, a goal and a reason, which keeps the requirement anchored to real value.

Capture data, integration and security needs

For every story, record:

• Data needed: which fields, from which system, and how current they must be
• Actions allowed: view only, or create, update, upload or approve
• Access rules: who in the client organisation can see it, and who cannot
• Integration: whether data is read live, synchronised on a schedule or pushed by events
• Volume: how many clients, users and records, now and in two or three years

Then capture the cross-cutting requirements that apply everywhere: authentication method, accessibility standard, supported browsers and devices, branding, languages, availability expectations, data retention and audit logging. For accessibility, many organisations reference the WCAG guidelines, which give testable success criteria.

Prioritise ruthlessly

A common technique is MoSCoW: must have, should have, could have and won't have this time. Must-haves are what the first release cannot launch without. Be strict: if everything is a must, the first release grows until it never ships. The "won't have" list is as valuable as the rest, because it records decisions and prevents scope from creeping back in quietly.

Write acceptance criteria

Each requirement needs criteria that tell everyone when it is met. Good acceptance criteria are specific and testable: "Invoices list shows invoice number, date, amount, status and a PDF download; only invoices for the user's own company appear; list loads within three seconds for a client with 500 invoices." Vague criteria, such as "invoices are easy to find", cannot be tested and lead to disputes.

Worked example: requirements for an engineering consultancy portal

Suppose an engineering consultancy wants a portal for its 300 corporate clients. After interviewing account managers, finance and four clients, its team writes requirements like these:

IDUser storyPriorityData sourceAcceptance criteriaR1As a client contact, I want to see the status of my projects, so I do not need to email for updatesMustProject system, synced hourlyLists only the company's projects with stage, next milestone and date; updates within one hour of changeR2As a client finance contact, I want to download invoices, so I can reconcile accountsMustAccounting system, synced dailyShows invoices from the last 24 months with PDF; finance role onlyR3As a client contact, I want to upload drawings to a project, so I do not send large email attachmentsMustPortal storage, linked to projectAccepts listed file types up to an agreed size; virus-scanned; project team notifiedR4As a client admin, I want to invite and remove colleagues, so access stays currentShouldPortal user storeAdmin can invite by email, assign role and deactivate; changes loggedR5As a client contact, I want to approve change requests online, so approvals are recordedShouldProject systemApproval records user, time and version; project manager notifiedR6As a client contact, I want to pay invoices by cardCouldPayment providerDeferred to a later phaseR7Live chat with engineersWon't (this release)Not applicableRecorded for future review

The team adds cross-cutting requirements: single sign-on for staff, email and password with multi-factor authentication for clients, WCAG 2.2 AA as the accessibility target, and audit logs of downloads and approvals. The priorities, sources and limits are this consultancy's choices.

From requirements to a plan

With prioritised requirements, a supplier or internal team can estimate each item, design the integrations and propose phases. A typical first release covers the must-haves only, launched to a pilot group of clients. Feedback from the pilot then reshapes the should-haves before wider rollout.

Keep the requirements document alive. When something changes, update it and note the reason, so the document remains the single description of what the portal does.

Common mistakes

• Starting with screen designs before agreeing what users need to do
• Leaving clients out of requirements gathering entirely
• Requirements that name features but not data sources or access rules
• Everything marked as a must-have
• No acceptance criteria, so "done" is a matter of opinion
• Forgetting non-functional needs such as accessibility, audit and volumes

Once requirements are clear, our guide to client portal development covers architecture and security. If your clients' data lives in Zoho CRM, see our comparison of a Zoho CRM client portal and a custom build.

Frequently Asked Questions

What should client portal requirements include?

User types, user stories with priorities, data sources and freshness, allowed actions, access rules, integrations, volumes, and cross-cutting needs such as authentication, accessibility and audit logging.

How do we gather client portal requirements?

Interview client-facing staff, finance, operations and IT, review the questions clients most often ask, and talk to a few clients directly before writing user stories.

What is MoSCoW prioritisation?

A method that sorts requirements into must have, should have, could have and won't have this time, so the first release contains only what it truly needs.

Why do client portal requirements need acceptance criteria?

Acceptance criteria make each requirement testable, so the team, supplier and stakeholders agree on when it is complete and disputes are avoided.

Plan your portal with us

We help businesses define client portal requirements and then design and build portals connected to their CRM and back-office systems. See our custom app development services, or talk to us about your portal.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.