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://govforms.uk, 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. Account and environment API limits apply. 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 (1,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.

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.