Portal SDK: Project API

The Portal SDK lets an embedded portal show a customer their onboarding project — its fields, milestones, tasks, and comments — and let them make the changes you allow. It has two layers:

React SDK

@statisfy/portal-react — drop-in components (<OnboardingProject/>, <ProjectModule/>, <Comments/>) and headless hooks (useProject, useComments).

REST API

The /sdk/v1 endpoints the React SDK calls. Use them directly if you’re not on React.

Everything is scoped to the customer in the session token — the portal never sends a customer id, and a project or task that isn’t the session’s is reported as 404 (existence is never leaked).

Authentication

Every call needs a portal session token (a short-lived JWT) as a bearer, plus your publishable key:

Authorization: Bearer <portal-session-token>
X-Statisfy-Publishable-Key: <publishable_key>

The session token comes from the portal’s passwordless sign-in — the customer enters an emailed one-time code and Statisfy returns a token scoped to them. The React SDK does all of this for you: <PortalAuthGate> owns the sign-in and refresh, and supplies <StatisfyProvider>. See Portal sign-in for the raw endpoints, and Publishable keys to create a key.

Visibility is enforced server-side. A real (non-preview) external viewer only receives fields, tasks, and comments that have been shared with the customer — see External sharing. An internal preview session sees everything.

What the customer can see and edit

Fields marked Internal are removed from the response entirely.
Tasks hidden from the portal are dropped from the task list.
Comments that weren’t shared with the customer are filtered out; comments the customer posts are always shared.
Writes are gated by meta.can_edit and each field’s editable flag.

REST API

Base path: /sdk/v1. All responses are JSON. Error responses:

Status	Shape
`400` `401` `403` `404`	`{ "detail": { "code": "...", "message": "..." } }`
`422` (validation error)	`{ "detail": [{ "loc": ["body", "field_name"], "msg": "...", "type": "..." }] }` — `detail` is an array of validation-error objects.

Resolve the onboarding project

GET /sdk/v1/config/portal

Returns the customer’s onboarding project id under onboarding_project__c_, which you then read with GET /projects/{id}.

{ "data": { "onboarding_project__c_": "1102" }, "meta": { "module": "portal" } }

Where that id comes from: onboarding_project__c_ is the Onboarding Project field on the Account — a system lookup field (pointing at a project) provisioned automatically — you never create it. The endpoint resolves it for the account the session token is scoped to, so each signed-in customer gets their own project with no id in your code. To make it resolve, set that field on the account: open the account record and pick its project in Onboarding Project, or populate it in bulk via import, the API, or field automation. An account whose field is empty returns null here, and <OnboardingProject/> renders its empty state instead of falling back to another account’s project. <OnboardingProject/> and <ProjectModule/> split on where the project id comes from. OnboardingProject reads this account field automatically — each signed-in customer sees their own project, no configuration beyond a configId. ProjectModule instead shows one project the portal’s author pins in Settings, the same project for every viewer; it’s visible only to the account that owns the pinned project, and every other signed-in account gets the empty state. Use OnboardingProject for the common per-account case; reach for ProjectModule only when every viewer should land on the same project.

In Portal Studio the field is surfaced in Settings → Components as the shared, Locked property “Onboarding project source” — read-only, because it is pinned platform-wide: re-pointing it would change onboarding for every portal at once. Configure the per-account value in Statisfy, not in the portal.

Read a project

GET /sdk/v1/projects/{project_id}

Returns the project’s values, human-readable display strings, field schema, server-ordered tasks, and a progress meter.

{
  "data": {
    "id": "1102",
    "properties": { "title": "New Onboarding", "status": "42", "due_date": "2026-07-04" },
    "display": { "status": "In Progress" },
    "schema": [ { "key": "status", "label": "Status", "type": "select", "editable": false, "options": [] } ],
    "progress": { "percent": 40, "completed": 2, "total": 5 },
    "tasks": [ { "id": "t1", "parent_id": null, "is_milestone": true, "status": "9", "step_status": "current", "properties": {}, "display": {} } ],
    "tasks_schema": [ { "key": "status", "label": "Status", "type": "select", "editable": true, "options": [] } ]
  },
  "meta": { "can_edit": true }
}

Render display[key] ?? properties[key]; send only canonical properties back on writes. tasks is a flat, depth-first list — build the milestone → subtask tree client-side from parent_id, and never re-sort it.

Update a project or task

PATCH /sdk/v1/projects/{project_id}
PATCH /sdk/v1/projects/{project_id}/tasks/{task_id}

Body is the changed canonical values only:

{ "properties": { "status": "10" } }

Both return the refreshed project payload. A non-editable field or invalid option is rejected with a 400 (not_editable / invalid_option / invalid_type).

Comments

GET  /sdk/v1/projects/{project_id}/comments
POST /sdk/v1/projects/{project_id}/comments
GET  /sdk/v1/projects/{project_id}/tasks/{task_id}/comments
POST /sdk/v1/projects/{project_id}/tasks/{task_id}/comments
PATCH /sdk/v1/projects/{project_id}/comments/{comment_id}

GET returns customer-visible comments oldest-first:

{ "data": [ { "id": 7, "value": "Welcome aboard!", "author_id": "p_1", "author_name": "Alex", "created_at": "2026-07-04T10:00:00Z", "updated_at": null, "visibility": "external", "can_edit": false } ] }

POST takes { "value": "..." } and returns the created comment. Portal-posted comments are always shared with the customer. PATCH (author only) edits the text.

Field	Meaning
`visibility`	`external` (shared with the customer) — internal comments are never returned here.
`can_edit`	`true` when the session’s person authored it.

React SDK

Install and wrap your app in <StatisfyProvider> (see Portals overview); it supplies the base URL, token minting, and publishable key to every hook and component.

`<OnboardingProject/>`

The signed-in account’s own onboarding project — header, progress, milestone journey, editable task list, project comments, and a task-detail drawer, resolved from the account field described above. configId is required: it’s what puts the component in the portal’s config manifest (so its Settings card renders), and without it the component can never resolve — there’s no embed-mode fallback.

import { OnboardingProject } from '@statisfy/portal-react'

<OnboardingProject configId="onboarding" />

It distinguishes three states: resolving (renders nothing), resolved with the field unset (“No onboarding project is set up for your account yet.”), and a failed config fetch (a distinct “couldn’t load configuration” message) — so a transient network error is never reported to a customer as “you have no project.”

`<ProjectModule/>`

The pre-assembled view of one project pinned by the portal’s author — the same project for every viewer, not each account’s own. In a portal, configId names this instance’s config slot and the pinned project id comes from the portal’s Settings; outside a portal, pass projectId directly.

import { ProjectModule } from '@statisfy/portal-react'

// Inside a portal: configId names the config slot; the project comes from Settings.
<ProjectModule configId="pinned-project" />

// Outside a portal: pass the project id directly.
<ProjectModule projectId="1102" />

Passing both props is allowed — configId wins and projectId is ignored (with a console warning in development). The pinned project resolves against the signed-in account, so only users of the account that owns it can see it; everyone else gets the empty state. That’s intended: use OnboardingProject above for a per-account view.

`<Comments/>`

A standalone comment thread + composer — project-level, or task-level with a taskId. Used inside <ProjectModule/>, but also available on its own for custom layouts.

import { Comments } from '@statisfy/portal-react'

<Comments projectId="1102" />                 {/* project thread */}
<Comments projectId="1102" taskId="t1" />      {/* task thread */}

`useProject(projectId?)`

Headless data hook for custom layouts. Owns the config → project resolve, the milestone/subtask tree, and optimistic task/project writes with rollback.

import { useProject } from '@statisfy/portal-react'

const { project, milestones, tasksByParent, canEdit, loading, error, updateTask } = useProject()
await updateTask('t1', { status: '10' })

The assembled equivalent of the no-arg resolve above is <OnboardingProject configId="onboarding" />.

`useComments(projectId, taskId?)`

Headless comments hook. Loads customer-visible comments and posts new ones (optimistically appended).

import { useComments } from '@statisfy/portal-react'

const { comments, loading, posting, addComment } = useComments('1102', 't1')
await addComment('Thanks — looks good!')

`createProjectClient(config)`

The React-unaware transport, if you want to call the API without hooks. Attaches the bearer token and publishable key on every request.

import { createProjectClient } from '@statisfy/portal-react'

const client = createProjectClient({ baseUrl, getToken, publishableKey })
const { data } = await client.getProject('1102')
await client.addTaskComment('1102', 't1', 'Done!')

Method	Endpoint
`getConfig(module)`	`GET /config/{module}`
`getProject(id)`	`GET /projects/{id}`
`patchProject(id, properties)`	`PATCH /projects/{id}`
`patchTask(id, taskId, properties)`	`PATCH /projects/{id}/tasks/{taskId}`
`getProjectComments(id)` / `addProjectComment(id, value)`	`GET` / `POST /projects/{id}/comments`
`getTaskComments(id, taskId)` / `addTaskComment(id, taskId, value)`	`GET` / `POST /projects/{id}/tasks/{taskId}/comments`
`editComment(projectId, commentId, value)`	`PATCH /projects/{id}/comments/{commentId}`

Getting Started

Accounts

People & Contacts

Opportunities

Activities

Views

Filters & Custom Fields

Projects

Tasks

Reports

Workflows

Dashboard

Workbench

Stella AI

Campaigns

Knowledge Base

Approvals

Portals

Statisfy SDK

Digital Workers

Portal SDK: Project API

React SDK

REST API

Authentication

What the customer can see and edit

REST API

Resolve the onboarding project

Read a project

Update a project or task

Comments

React SDK

`<OnboardingProject/>`

`<ProjectModule/>`

`<Comments/>`

`useProject(projectId?)`

`useComments(projectId, taskId?)`

`createProjectClient(config)`

React SDK

REST API

​Authentication

​What the customer can see and edit

​REST API

​Resolve the onboarding project

​Read a project

​Update a project or task

​Comments

​React SDK

​<OnboardingProject/>

​<ProjectModule/>

​<Comments/>

​useProject(projectId?)

​useComments(projectId, taskId?)

​createProjectClient(config)

Authentication

What the customer can see and edit

REST API

Resolve the onboarding project

Read a project

Update a project or task

Comments

React SDK

`<OnboardingProject/>`

`<ProjectModule/>`

`<Comments/>`

`useProject(projectId?)`

`useComments(projectId, taskId?)`

`createProjectClient(config)`