# Read, update and deploy User portal settings

Source: https://govform.com/resources/documentation/article/33-12-api-user-portal
Topic: Govform API & MCP

Manage the library's User portal through REST. These endpoints configure its title, introduction, selected services and Collection programmes, cards and domain. They do not return respondent answers or activity.

## Host, endpoints and permissions

Use `https://app.govform.com`, or your private Builder host. The base path is /builder/libraries/{libraryId}/api/user-portal. Authenticate with your library API key or GovformsApiHmac and send JSON for writes.

| Method and path | Permission | Result |
| --- | --- | --- |
| `GET /builder/libraries/{libraryId}/api/user-portal` | apiPortalRead | Read settings, revision and environment deployment metadata. |
| `PATCH /builder/libraries/{libraryId}/api/user-portal` | apiPortalWrite | Save a partial settings update using the expected revision. |
| `POST /builder/libraries/{libraryId}/api/user-portal/deployments` | apiPortalDeploy | Prepare deployment and return its confirmation link. |

Form-write and form-deployment permissions do not grant these portal permissions. For Cloud accounts, each successful GET, PATCH or POST operation above uses 5 API units. Government Cloud accounts are exempt from these quotas. Check the API-unit response headers for usage.

## Read settings and choices

GET accepts includeChoices=true, offset (0–5000) and limit (1–100, default 100). Without includeChoices it reads the saved settings and deployment state. The response includes settings, revision, previewUrl, builderUrl and environments, including deployed settings, dates, actor, URL and current status.

With choices requested, the response also includes a bounded selection of service and programme metadata, domainChoices, nextOffset and catalogueLimitReached. Continue with nextOffset when present; the selection catalogue is capped at 5,000 entries. It does not include full service definitions or credentials.

## Save a partial update

```http
PATCH /builder/libraries/demo-library/api/user-portal
Authorization: GovformsApiKey <key-id>:<key-secret>
Content-Type: application/json
```

```json
{
  "expectedRevision": "revision-from-get",
  "settings": {
    "title": "Your applications",
    "introduction": "Start an application or check its progress.",
    "serviceIds": ["apply"],
    "collectionProgrammeIds": [],
    "cards": {
      "service:apply": {"title": "Apply for a grant", "description": "Start your application."}
    }
  }
}
```

expectedRevision is required, including the empty string for a library without a revision. A stale revision returns 409: reread before making another patch. The saved result includes the new revision.

Omitted settings are preserved. Supplied arrays and the cards map replace those properties, so include entries you want to keep. Empty text clears overrides, and empty arrays clear selections. Card keys use service:{serviceId} or collection:{collectionProgrammeId}; cards for removed selections are discarded. cardOrder controls the selected card order.

Settings accept title (100 characters), introduction (5,000), serviceIds, collectionProgrammeIds, cardOrder, cards, domain and redirectRoot. Cards accept title (100), description (500), imageRef, imageFilename, originalImageRef, originalImageFilename, imageDisplay (crop or natural), imageDecorative and imageAltText (300). Use existing library-owned images; upload and crop new images in Builder. Informative images require alternative text.

Select authenticated ordinary services rather than patterns or managed Collection forms. Select a Collection programme to include its current and future Collections. Existing unavailable selections can be retained or removed and are hidden from respondents. Domain choices use active shared service domains in the library; this API does not provision or transfer a domain. redirectRoot with a selected domain redirects its homepage after Production deployment.

## Categories and homepage layouts

Portal categories organise included services and programmes. They are separate from Builder service labels and do not expose respondent answers or activity.

| Setting | Contract |
| --- | --- |
| `displayMode` | `flat` (Service cards, the default), `categories` (Category cards), or `grouped` (Grouped services). |
| `categories` | Up to 100 objects with a unique stable `id`, required `title` and ordered `memberKeys`. Members use `service:{id}` or `collection:{programmeId}` and must be included in the final selections. Limits are 5,000 members per category and 25,000 memberships overall. |
| Category presentation | Optional description and image fields belong on the category object, with the same library-image and alternative-text validation as cards. |
| `cards` | An individual card can set `showOnHomepage: true` to appear directly in Category cards layout as well as within categories. Uncategorised services remain directly available. |
| `cardOrder` | Also accepts `category:{id}`, with up to 5,100 entries. Category member order comes from `memberKeys`. |

A service or programme can be in several categories; its applications and overall activity totals stay unique. Changing layouts preserves the configured categories and cards.

A layout-only patch preserves categories, card overrides and selections:

```json
{"expectedRevision": "revision-from-latest-read", "settings": {"displayMode": "grouped"}}
```

Supplying `categories` replaces the entire array. Read and merge wanted entries first, retain category IDs when renaming, then save with the latest revision. An omitted array is preserved; deselecting a service in a selection-only patch prunes its old memberships. Removing a category keeps its services. Empty categories stay in configuration but are hidden from the homepage until a member is available.

Category pages use `/prototypes/{libraryId}/_portal/categories/{categoryId}` or `/services/{libraryId}/_portal/categories/{categoryId}` under the existing portal authentication. Category filters also apply to Things to do and My activity and persist through pagination. These are respondent pages, not additional configuration API endpoints.

Use matching Builder, runtime and client schema support before configuring categories. Deploy the saved portal and verify the environment status. For the UI workflow, see [Set up a User portal and service categories](<https://govform.com/resources/documentation/article/20-13-library-user-portal>).

## Deploy portal settings

```json
{"expectedRevision": "revision-from-save", "environment": "qa"}
```

POST that body to /builder/libraries/{libraryId}/api/user-portal/deployments. The environment must be configured: qa, production or staging where enabled. The result contains deploymentId, confirmationUrl and status: "requires-browser". An authorised person must open the confirmation URL and complete the deployment in Builder. Reread environments to verify completion.

Saving affects User view. Portal deployment is separate from deploying service definitions, authentication or branding.

## Errors

400 indicates invalid input; 403 invalid credentials or missing permission; 409 a stale revision or conflicting configuration. Capacity limits return 429. Builder errors use error.message; follow Retry-After for limits.

See [API key settings](<https://govform.com/resources/documentation/article/30-govforms-api-key-settings>) and the [endpoint index](<https://govform.com/resources/documentation/article/33-10-api-endpoint-reference>).

See [authentication headers](<https://govform.com/resources/documentation/article/33-govforms-api#authentication-headers>) for raw-key and HMAC formats.

## Introduction mode and card sizes

`introductionMode` selects markdown or html for the introduction (up to 5,000 characters). `categoryCardSize` controls the category-card homepage grid. `categories[].cardSize` controls the service cards inside that category's page.

Both sizes accept `large`, `standard` or `compact`. Omitted homepage size defaults to standard; omitted category-page size defaults to compact. Explicit sizes are preserved. Include existing category entries/memberships when supplying a replacement categories array.

## Content, templates and status labels

These optional properties change presentation only. Each replaces its whole property when supplied. Restore defaults with `{}` for navLabels, content or statusLabels; `[]` for activityColumns or taskColumns; `{"tables":[]}` for overview; or `{"template":""}` for either card template.

| Property | Shape and limits |
| --- | --- |
| `navLabels` | `{services?, overview?, tasks?, activity?}`, up to 40 characters each. Labels are plain text and apply to navigation and page headings. The Services page heading defaults to “Your services”; a custom services label replaces it. Category pages keep their category title. |
| `content` | `{servicesEmpty?, overviewIntro?, tasksIntro?, tasksEmpty?, activityIntro?, activityEmpty?}`, each `{template, mode?}` up to 10,000 characters. `mode` is markdown (default) or html. |
| `serviceCardTemplate`, `taskCardTemplate` | `{template, mode?}`, up to 5,000 characters. |
| `activityColumns` | Up to 6 `{heading, template}`; heading up to 60 and template up to 2,000 characters, rendered per row as HTML. |
| `taskColumns` | Up to 6 `{heading, template}` with the same limits. Shows Things to do as a table instead of cards; each row keeps its action button. |
| `statusLabels` | `{"<status>": {text?, colour?}}` keyed by canonical status; text up to 50 characters; colour grey, green, turquoise, blue, light-blue, purple, pink, red, orange or yellow. |

Templates are Liquid followed by Markdown or HTML and are sanitised as service content. Invalid Liquid returns 400. Variables: `portal.title`, `portal.libraryName`, `user.name`, `section` and `attentionCount` (on Services/category pages); for task cards and activity columns `item.name`, `reference`, `status`, `statusLabel`, `statusTag`, `createdAt`, `updatedAt`, `dueAt`, `detailUrl`, `actionUrl` (GET actions only; empty for Collection POST actions), `actionLabel` and `kind`; for card templates `card.title`, `description`, `kind`, `url`, `attentionCount`, `draftCount` and `serviceCount`. Templates never receive answers, except that My activity columns can show questions selected in `dataSources.activity.answerFields` as `item.answers["fieldId"]`. The introduction also evaluates Liquid; wrap literal Liquid delimiters in a complete raw block, for example `{% raw %}{{{% endraw %}`. Filters and status rules keep canonical status names.

```
{"expectedRevision":"revision-from-get","settings":{"navLabels":{"tasks":"Your actions"},"statusLabels":{"Changes requested":{"text":"Action needed","colour":"orange"}},"activityColumns":[{"heading":"Application","template":"<a href=\"{{ item.detailUrl }}\">{{ item.name }}</a>"},{"heading":"Status","template":"{{ item.statusTag }}"}]}}
```

Portal CSS is the library style setting `stylePostSass` (Custom CSS overrides), applied per environment through style settings. Prefix rules with `.gf-portal-page`.

## Data sources and Overview

My activity and Things to do are data sources. Read with `includeDataSources=true` to list them. Supplying `settings.dataSources` replaces the whole property, so include every source you want to keep.

| Property | Shape and behaviour |
| --- | --- |
| `dataSources.activity` | `{fixed?, filters?, direction?, answerFields?}`. `fixed` accepts service, reference, status, from and to; `filters` lists what users may change (service, reference, status, updatedDate); `direction` is ascending or descending by last updated. Up to six `answerFields` `{source, formId, fieldId, fixedValue?, allowFilter?}` select direct text, numeric, single-choice or date questions. Discover them with `fieldSource` and, for a Collection programme, `fieldFormId`; API keys also need form read or write permission. |
| `dataSources.tasks` | `{fixed?: {service?}, direction?}`. A fixed service limits Things to do, its invitations and the things-to-do counts on service cards to that service. There is one item per response that needs the user’s attention. |
| `overview` | `{tables}`: up to 4 `{source, heading, countLabel?, statuses?, openCasesOnly?}`. `source` is activity or tasks; heading and countLabel are up to 60 characters. |

Overview is an optional page listed after Services once it has a table; Services remains the landing page. Each table shows the first 10 rows of its data source, using that source’s columns and fixed filters, and links to the source’s own page for paging and filtering. A table with `countLabel` shows the total number of rows it selects, so a total always agrees with its table.

`statuses` and `openCasesOnly` narrow a My activity table only. `statuses` takes canonical status names; a status fixed on the data source takes precedence. `openCasesOnly` leaves out responses whose case your team has closed in Response Hub. Accepting a response does not close its case, and Collection responses are not affected.

```json
{"expectedRevision": "revision-from-get", "settings": {
  "dataSources": {"activity": {"fixed": {"service": "service:notify"}}, "tasks": {"fixed": {"service": "service:notify"}}},
  "overview": {"tables": [
    {"source": "activity", "heading": "Your open cases", "countLabel": "Open notifications",
     "statuses": ["Submitted", "Under review", "Changes requested", "Updated", "Returned", "Accepted", "Complete"], "openCasesOnly": true},
    {"source": "tasks", "heading": "Things we need from you", "countLabel": "Actions to complete"}]}}}
```

Rows, totals and linked records follow the signed-in user’s existing access: their own responses and their organisation’s Collection assignments. Change requests have no due date, and there is no combined history across responses; each row links to its record, where the user can open its answer changes and comment history. Save, then deploy the portal to each environment.

### Choose portal data sources

Library administrators can configure My activity in Content and labels or through MCP. Read `get_user_portal` with `includeDataSources=true`. Use `fieldSource` with an included service or Collection programme key to discover eligible question IDs. For a Collection, select a returned `fieldFormId`. Pass `nextFieldOffset` as `fieldOffset` for more questions or managed forms. Service choices have a separate `offset`. API keys also need form read or write permission to discover fields.

Set `settings.dataSources` with the existing revision-checked portal update. My activity supports fixed and user-selectable filters. Clear or replace a fixed service and any selected fields for that service before removing it from the portal. Numeric answer filters accept values that can be represented exactly as Decimal128. Select simple questions in `activity.answerFields` by source, formId and fieldId. Selected questions and a fixed service must use the same sign-in method as the portal. A fixed answer value must be a single line, and questions that accept several lines can be shown but not filtered. Questions that share a field ID share one user filter. An activity column can display `{{ item.answers["fieldId"] | escape }}`. Ordinary activity lists owned responses. Collection activity includes unstarted assignments for current members. Started responses also require a matching assignment, response and journey. A fixed answer filter applies within its bound form. Only configured eligible answers from the current form snapshot can appear in a cell or match an answer filter. Saving affects User view. Deploy to each environment separately.
