Portal API

Portal routes are called by the portal worker via service token. The portal worker authenticates the client and forwards context via headers:

• X-Portal-Company-Id — the authenticated client’s company ID (required)
• X-Portal-User-Role — viewer, collaborator, or admin
• X-Portal-User-Id — the portal user’s ID
• X-Portal-Group-Company-Ids — comma-separated company IDs for group-aware queries (parent + children)

All routes enforce company scoping on every query. Endpoints that write data require collaborator or admin role.

Dashboard

Get Dashboard

GET /api/portal/dashboard

Returns an overview for the client including active projects with task progress, financial summary, recent activity, upcoming milestones, and latest announcements.

Response: { projects, taskCounts, financial, recentActivity, milestones, announcements }

• financial includes total_invoiced, total_outstanding, total_overdue
• Group-aware: uses all companies in the group

Projects

List Projects

GET /api/portal/projects

Query parameters:

Param	Type	Description
status	string	Filter by project status

Response: { projects, taskCounts }

Get Project

GET /api/portal/projects/:id

Response: { project, goals, members, aiSummary, decisions }

Includes the project’s goals, team members, latest AI summary, and recent decisions.

Get Project Tasks

GET /api/portal/projects/:id/tasks

Returns non-private tasks for the project with status, priority, type, and assignee details.

Response: { tasks }

Get Project Roadmap

GET /api/portal/projects/:id/roadmap

Returns the roadmap linked to the project, if any, with its items.

Response: { roadmap, items }

Get Project Decisions

GET /api/portal/projects/:id/decisions

Returns all decisions for the project with the decider’s name.

Response: { decisions }

Budgets

List Budgets

GET /api/portal/budgets

Returns budgets linked to the client’s projects or deals. Group-aware.

Response: { budgets }

Get Budget

GET /api/portal/budgets/:id

Response: { budget, lineItems }

Approve Budget

POST /api/portal/budgets/:id/approve

Role required: collaborator or admin

Approves a budget that has pending_approval status. Logs approval in history.

Response: { ok: true }

Invoices

List Invoices

GET /api/portal/invoices

Returns all invoices for the client’s companies. Group-aware.

Response: { invoices }

Get Invoice

GET /api/portal/invoices/:id

Response: { invoice, lineItems, payments }

Contracts

List Contracts

GET /api/portal/contracts

Returns contracts where any signer’s email belongs to the client’s company contacts. Group-aware.

Response: { contracts }

Pages

List Pages

GET /api/portal/pages

Returns published pages linked to the client’s company or projects. Group-aware.

Response: { pages }

Get Page

GET /api/portal/pages/:id

Returns a single published page with its rich content.

Response: { page }

Notes

List Notes

GET /api/portal/notes

Returns client-visible notes across the client’s projects, deals, budgets, and invoices. Group-aware. Limited to 100 results.

Response: { notes }

Create Note

POST /api/portal/notes

Role required: collaborator or admin

Request body:

Field	Type	Description
resourceType	string	project or invoice
resourceId	string	Resource ID
content	string	Note content
parentId	string	Optional parent note ID (for replies)
portalUserId	string	Portal user ID

Response: { id } (201)

History

Get History

GET /api/portal/history

Returns recent history entries for the client’s projects, invoices, and budgets. Limited to 50 results.

Response: { history }

Team

Get Team

GET /api/portal/team

Returns team members and leads across the client’s active projects. Group-aware.

Response: { team, leads }

Announcements

List Announcements

GET /api/portal/announcements

Returns the latest 20 company-category announcements.

Response: { announcements }

Client Requests

Create Request

POST /api/portal/requests

Role required: collaborator or admin

Creates a task from a client request. Auto-assigns SLA if applicable. Notifies the delivery manager.

Request body:

Field	Type	Description
title	string	Request title (required)
description	string	Request description
priority	string	Priority value (e.g. high, medium)
projectId	string	Optional project to attach the request to
portalUserId	string	Portal user ID

Response: { taskId, ok: true } (201)

Notifications

List Notifications

GET /api/portal/notifications

Query parameters:

Param	Type	Description
filter	string	all (default), unread, or archived
limit	number	Max results (default: 50, max: 100)
offset	number	Pagination offset (default: 0)

Response: { notifications, limit, offset }

Unread Count

GET /api/portal/notifications/unread-count

Response: { unread_count }

Mark as Read

POST /api/portal/notifications/:id/read

Response: { ok: true }

Mark All as Read

POST /api/portal/notifications/read-all

Response: { ok: true }

Get Notification Preferences

GET /api/portal/notifications/preferences

Returns notification types that support portal delivery, merged with the user’s saved preferences.

Response: { preferences }

Update Notification Preferences

PUT /api/portal/notifications/preferences

Request body:

Field	Type	Description
preferences	array	Array of { notification_type, channel_in_app, channel_email }

Response: { ok: true }

Connections

List Connections

GET /api/portal/connections

Returns platform connections for the client’s company. Only available when dashboard_enabled is true on the client profile.

Response: { connections, dashboard_enabled }

Create Connection

POST /api/portal/connections

Connects a new platform (e.g. Shopify, Google Ads). Tests the connection, encrypts credentials, and stores. Notifies the assigned DM.

Request body:

Field	Type	Description
platform	string	Platform key
credentials	object	Platform-specific credentials
display_name	string	Optional display name

Response: { connection } (201)

Delete Connection

DELETE /api/portal/connections/:id

Disconnects a client-managed connection. Cannot disconnect agency-managed connections.

Response: { ok: true }

Sync Connections

POST /api/portal/connections/sync

Triggers an async sync of all connected platforms for the client.

Response: { message: "Sync started" } (202)

Results

Get Results

GET /api/portal/results

Returns aggregated metrics for the client with period-over-period comparison and goal tracking. Only available when dashboard_enabled is true.

Query parameters:

Param	Type	Description
period_type	string	week, month (default), quarter, or year
period_end	string	End date (YYYY-MM-DD, default: today)

Response: { period, metrics, insight, connected_platforms, dashboard_enabled }

Each metric includes value, prior_value, delta_pct, target, and tracking_status.

Get Campaign Results

GET /api/portal/results/campaigns

Returns campaign-level performance data aggregated over the selected period.

Query parameters:

Param	Type	Description
period_type	string	week, month (default), quarter, or year
period_end	string	End date (YYYY-MM-DD)
platform	string	Filter by ad platform
sort_by	string	Sort field (default: spend). Options: spend, impressions, clicks, conversions, roas, cpa, etc.
sort_dir	string	asc or desc (default)

Response: { period, campaigns, totals }

Ask AI

POST /api/portal/results/ask

Ask a natural-language question about the client’s performance data.

Request body:

Field	Type	Description
question	string	The question to ask

Response: { answer }

Questionnaire

Get Questionnaire

GET /api/portal/questionnaire

Returns the client’s success profile questionnaire responses.

Response: { profile }

Submit Questionnaire

POST /api/portal/questionnaire

Role required: collaborator or admin

Submits or updates the client success profile. Can also create client goals. Notifies the assigned DM on first completion.

Request body:

Field	Type	Description
financial_year_start	string	Financial year start
financial_year_end	string	Financial year end
key_trading_periods	string	Key trading periods
channel_online_pct	number	Online channel percentage
channel_instore_pct	number	In-store channel percentage
channel_wholesale_pct	number	Wholesale channel percentage
celebration_vision	string	Celebration vision
growth_priorities_text	string	Growth priorities
company_direction_text	string	Company direction
goals	array	Array of goal objects with metric, target, unit, period, metric_key, metric_label

Response: { ok: true }

QBRs

List QBRs

GET /api/portal/qbrs

Returns presented QBRs for the client. Internal sections are filtered based on portal_visibility settings.

Response: { qbrs }

Onboarding

Get Onboarding Progress

GET /api/portal/onboarding

Returns the client’s onboarding template, stages, milestones, and progress.

Response: { template, stages, total_milestones, completed_milestones, completion_percentage, current_stage_type, started_at, completed_at }