Govform.com
Skip to article
DocumentationGuides & reference

Search across guides and reference articles. Try “email”, “API” or “conditions”.

Govform API & MCP

Read, update and deploy User portal settings

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

PATCH /builder/libraries/demo-library/api/user-portal
Authorization: GovformsApiKey <key-id>:<key-secret>
Content-Type: application/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.

SettingContract
displayModeflat (Service cards, the default), categories (Category cards), or grouped (Grouped services).
categoriesUp 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 presentationOptional description and image fields belong on the category object, with the same library-image and alternative-text validation as cards.
cardsAn individual card can set showOnHomepage: true to appear directly in Category cards layout as well as within categories. Uncategorised services remain directly available.
cardOrderAlso 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:

{"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.

Deploy portal settings

{"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 and the endpoint index.

See 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.

PropertyShape 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.
activityColumnsUp to 6 {heading, template}; heading up to 60 and template up to 2,000 characters, rendered per row as HTML.
taskColumnsUp 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.

PropertyShape 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.

{"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.

More in developers