Servicing configuration

The configuration plane covers four administrative surfaces: the case types and reasons a tenant services, the workflow definitions those types run, the allocation policy and queue coverage that route the work, and the fields a case presents or a task requires before completion. Each is a closed configuration object with an audited actor and reason — configuring them creates no table, no migration, and no second form lifecycle.

Configuration authority is separate from doing the work: an administrator who can change a case type’s fields does not thereby gain permission to open, transition, or close cases — and authoring a workflow definition does not carry the separate authority to activate one.

Case-type administration

GET/POST /v1/servicing/admin/case-types and PUT /v1/servicing/admin/case-types/{caseTypeCode} administer the catalog itself. A new case type is born disabled, with no reasons and empty field definitions — invisible to workers until deliberately enabled, and enabling requires at least one enabled reason and an ACTIVE-resolvable workflow for every enabled reason. Reasons are added and updated under the type (.../reasons, .../reasons/{reasonCode}), each carrying its handling mode and optional workflow-key override, and PUT .../review-timers replaces the type’s recurring-review rows in one call.

Workflow definitions

/v1/servicing/admin/workflow-definitions is the builder’s backend. A definition version moves DRAFT → ACTIVE → RETIRED (or is discarded as a draft), and only drafts can be edited. POST .../validate is a stateless dry-run that returns schema and reference findings anchored to stages; GET .../vocabulary returns everything a definition may reference — predicate sources and operators, named conditions, live task types with their closed outcome catalogs, queues, typed effects, wait statuses, priorities, and approval roles. Activation and retirement run under a separate promotion authority (ACTIVATE_SERVICING_WORKFLOW_DEFINITION), warn about stage keys dropped from the current ACTIVE version, and never rewrite running work: an open case stays pinned to the version it started on. GET .../export and POST .../import move definitions between environments as versioned bundles — unchanged definitions are skipped, changed ones become new drafts.

Allocation & queue coverage

GET/PUT /v1/servicing/admin/allocation hold the servicing-wide allocation policy: whether work is pushed automatically, reservation and concurrency limits, and the callback timing windows. GET /v1/servicing/admin/queues returns every enabled queue with its members, availability, open and unoffered work, and a staffing warning where one is due — an unstaffed queue is visible before its work silently accumulates — and POST .../{queueCode}/members adds and removes members as explicit auditable rows, never routing rules hidden inside a role.

Case field definitions

curl "$BASE/v1/servicing/admin/case-types/GENERAL_SUPPORT/field-definitions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

{
  "caseTypeCode": "GENERAL_SUPPORT",
  "fieldDefinitions": {
    "sections": [
      {
        "key": "service_details",
        "label": "Service details",
        "fields": [
          {
            "key": "requested_effective_date",
            "label": "Requested effective date",
            "type": "DATE",
            "requiredAt": "OPTIONAL"
          }
        ]
      }
    ]
  }
}

A definition is sections of fields. Each field declares a stable key, a display label, a type, and requiredAt — the point in the workflow at which the value becomes mandatory, which is what lets a field be optional at intake and required before closure.

PUT replaces the whole object and requires a reason:

{
  "fieldDefinitions": { "sections": [ /* the complete new definition */ ] },
  "reason": "Add the requested effective date to support work."
}

{
  "resourceId": 11,
  "caseTypeCode": "GENERAL_SUPPORT",
  "changes": { "fieldKeys": ["requested_effective_date"] }
}

Because the replacement is whole-object, read the current definition, modify it, and send it back. A PUT carrying only the new section drops every section you omitted. The response reports the resulting field keys, which is the cheapest way to confirm the write landed as intended.

The case type must already exist — created and enabled through the case-type administration surface above. The enabled types themselves are read by callers through GET /v1/servicing/case-types, which returns each type with its reasons, routing defaults, and current field definitions, and GET /v1/servicing/case-types/{caseTypeCode}/workflow projects the ACTIVE workflow shape a worker will actually traverse — see Case model & lifecycle.

Task completion fields

The task-type surface is the same shape, applied to what a worker must record when finishing work:

• GET /v1/servicing/admin/task-types/{taskTypeCode}/completion-field-definitions
• PUT /v1/servicing/admin/task-types/{taskTypeCode}/completion-field-definitions

{
  "completionFieldDefinitions": { "sections": [] },
  "reason": "Align completion evidence with the current workflow."
}

These fields are validated by POST /v1/servicing/tasks/{taskId}/complete, whose fields object must satisfy the current definition. That is the mechanism behind a rule like “a collections outreach task cannot be completed without recording whether identity was verified” — the requirement lives in configuration, not in a client-side form.

An empty sections array is valid and means the task type requires an outcome code and nothing more.

Configuration is versioned by use, not by draft

There is no separate publish or draft lifecycle here, and no second form-entry model. A replacement takes effect for subsequent validation; work already completed keeps the values it recorded under the definition in force at the time. If you need an approval workflow around a definition change, run it in your own change process — the API records the actor and reason, not an approval chain.