# Read and update caseworker portal settings

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

Enable Response Hub in the library before reading or changing caseworker portal settings.

Configure one caseworker portal for a library: selected services, case-type labels, a case title and answer fields. Each case is one response plus its caseworker form. These endpoints return configuration, not case records or respondent answers.

## Endpoints and permissions

Use your Builder host and library API key or GovformsApiHmac. Send JSON for writes.

| Method and path | API-key permission | Result |
| --- | --- | --- |
| `GET /builder/libraries/{libraryId}/api/caseworker-portal` | apiCaseworkerPortalRead | Saved settings and revision; optional service and field choices. |
| `PATCH /builder/libraries/{libraryId}/api/caseworker-portal` | apiCaseworkerPortalWrite | Save a partial settings update using the expected revision. |

These permissions are separate from form-write and User portal permissions. Both endpoints cost five API units per request for Cloud accounts. **Caseworker portal settings apply immediately on save, including Production.** They have no separate deployment step. Form definitions and completion settings still follow service deployment.

## Read settings and choices

GET returns `settings`, `revision`, `portalUrl`, `builderUrl` and `appliesOnSave: true`. Optional `includeChoices=true` returns service choices; use `offset` (zero or higher), `limit` (1–100, default 100) and the returned `nextOffset`. Optional `formId` returns fields from that saved Builder service and its selected caseworker form. Runtime answers may differ between environments; unavailable fields display a dash.

## Save settings

```json
{
  "expectedRevision": "revision-from-get",
  "settings": {
    "title": "Caseworker portal",
    "introduction": "Manage notifications and assessments.",
    "caseTypes": [{
      "formId": "event-notification",
      "label": "Event notification",
      "pluralLabel": "Event notifications",
      "columns": [],
      "details": []
    }]
  }
}
```

`expectedRevision` is required, including the empty string when GET returns it. A stale revision returns 409; reread before changing settings. Omitted properties remain unchanged. A supplied `caseTypes` array replaces the whole ordered list; include entries you want to keep. An empty array removes all case types.

Title is 1–150 characters, introduction up to 2,000. `customCss` (up to 50,000 characters) styles only the caseworker portal; an empty string removes it. Start each rule with `.gf-caseworker-app`. User portal and service styles stay in Library style settings. Select at most 100 distinct services from the library. Set `kind` to `case` (default), `information` or `reply`. Cases require a caseworker form selected in Response settings. Information and reply services can use their own queues without a staff form. Set `allowInvitations` to true to invite a named respondent to complete a signed-in service. Configure an optional `assessmentTarget` with integer `normalHours` and `peakHours` (1–8760), up to 24 inclusive `peakPeriods` with ISO dates `from` and `to`, and the staff Task List `milestoneTaskId`. The first submission starts the clock. `summaryField` uses the field object below to count single-choice answers in the type queue. Each case type has a service `formId`, `label` and `pluralLabel` (1–100 characters), optional `titleField`, and up to six `columns` and six `details`. Field objects contain `source` (`response` or `caseworker`), `formId`, `fieldId` and `label`. Use the returned field choices. Extra columns appear in the selected type's queue; the combined queue uses common columns. The page layout is fixed.

## Casework and completion

Administrators configure the browser experience under **Response Hub → Caseworker portal**. The Library Dashboard and Response Hub overview provide entry points; caseworker-only members enter the configured portal. The Account menu opens Response Hub for caseworker-only members and Library Dashboard for Builder users. Existing roles and environment access apply.

Case status is **New / In progress / Closed**, separate from review status and authored Task List tasks. **Assign case to me** assigns ownership; **Assign review to me** claims a review. **Response target** remains the existing response turnaround target.

Caseworker forms use `responseHubCaseworkerCompletion`: `form` (default) requires a completed assessment before acceptance; `caseClosure` is an ongoing Task List without an End page, completed by Close case in the staff editor. For ongoing forms, adding submission or workflow actions, selecting ongoing completion with actions already configured, or newly linking an ongoing form containing those actions returns HTTP 400. Move the work to a separate task using a page action, or use Complete the form in Response review to retain submission actions. Closing requires any required review to be accepted. Reopening an ongoing case reopens its form; a default assessment stays completed until explicitly reopened. Acceptance and its historical assessment evidence remain recorded. Staff answer history starts automatically at the first save. Collection responses retain default completion. Existing unlinked responses remain in Response Hub.

## MCP and Darcy

MCP exposes `get_caseworker_portal`, `update_caseworker_portal` and `govforms://docs/caseworker-portal`. OAuth writes require library administrator access, full form-design access and write scope, through the existing approval flow. Darcy uses `getAdministrationOptions({includeCaseworkerPortal:true})` and `caseworkerPortal.save` with administration confirmation. Casework remains in the browser; these configuration tools do not claim reviews, alter answers or close cases.

See the [API endpoint index](<https://govform.com/resources/documentation/article/33-10-api-endpoint-reference>) and [MCP capabilities](<https://govform.com/resources/documentation/article/33-14-mcp-capabilities>).
