Case effects

A case effect is how workflow automation acts. When a pinned workflow needs something done — cancel autopay, apply a restriction, open follow-up work — it creates a typed, durable effect that the executor performs. Callers observe and recover effects; they never create them.

Why the boundary is read-mostly

The three implemented routes are two reads and one recovery command:

There is deliberately no create route. effectType is a closed contract owned by the workflow definition, so no caller can submit an arbitrary command, URL, or effect payload and have the executor run it. That is the same rule the governed operations boundary applies to direct operations, expressed for automation.

Reading effects

curl "$BASE/v1/servicing/cases/1001/effects?status=FAILED&limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

{
  "items": [
    {
      "effectRef": "effect-cancel-autopay-1001-1",
      "caseId": 1001,
      "effectType": "CANCEL_AUTOPAY",
      "triggerType": "LMS_EVENT",
      "status": "COMPLETED",
      "attemptCount": 1,
      "createdAt": "2027-05-05T18:30:00Z",
      "completedAt": "2027-05-05T18:30:02Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

status and effectType are repeatable — send each value again to include several states or types in one read. triggerType, createdFrom, and createdTo take a single value.

This collection is the one current cursor-paged servicing list: it takes limit (1–200, default 50) plus an opaque newest-first cursor and returns nextCursor, while most servicing collections use limit/offset. Send nextCursor back unchanged and stop when it is null; offset and cursor are never interchangeable. See Pagination.

effectRef is a stable string, not a numeric ID, and it is the identifier the point read and the retry command both take. The point read adds the trigger, attempt history, timestamps, and redacted result or failure references — enough to explain what happened without exposing provider-native payloads.

Retry is recovery, not re-issue

Retry exists for one situation: an effect reached terminal FAILED and the underlying cause has since been resolved.

curl -X POST "$BASE/v1/servicing/cases/1001/effects/effect-cancel-autopay-1001-1?command=retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "The transient downstream failure has been resolved." }'

{
  "effectRef": "effect-cancel-autopay-1001-1",
  "status": "PENDING",
  "resourceId": 1001
}

Three properties matter:

• command=retry is required. The route accepts no other command, so the verb cannot be widened later by a client guessing at a parameter.
• reason is required. A retry is a recorded operational decision, not a refresh button.
• The effect returns to PENDING and the workflow executor performs the same typed operation. The retry does not carry a new payload, so it cannot become a way to change what the workflow decided to do.

An effect that is not terminally failed cannot be retried, and retrying does not duplicate an effect that a provider already accepted. Where an external side effect may already exist, it follows its own cancellation and reconciliation path instead.

Effects in the case workspace

Effects, action requests, and tasks answer three different questions on the same case, and conflating them hides work:

A failed effect is therefore not a failed task. Closing the task does not clear it, and the case’s closure criteria account for outstanding effects — a matter cannot be closed while the workflow still owes a committed operation.