Setup progress

Read a context’s aggregated setup and activation-readiness state in a single request to drive an onboarding checklist or setup wizard.

The setup-progress endpoint returns configured-resource counts, the last-run state, and activation readiness for a context in a single aggregate — so a setup wizard or onboarding checklist derives its state from one request instead of many.

Get setup progress

---

curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/setup-progress" \
  -H "Authorization: Bearer $TOKEN"

{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "sources": { "total": 2, "left": 1, "right": 1 },
  "fieldMaps": { "mappedSources": 2 },
  "matchRules": { "total": 3 },
  "schedules": { "total": 1 },
  "lastRun": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "completedAt": "2025-01-15T10:30:00Z"
  },
  "readiness": {
    "ready": true,
    "missing": []
  },
  "next": null
}

What it returns

---

• status — the context lifecycle status: DRAFT (being configured), ACTIVE (running), PAUSED (suspended), or ARCHIVED (retired).
• sources — source counts split by matching side: total, left, right.
• fieldMaps.mappedSources — number of mapped sources: those with a field map, plus CAMT.053 sources, which are self-mapped (the parser embeds the ISO 20022 mapping and ignores field maps).
• matchRules.total — match-rule count for the context.
• schedules.total — schedule count for the context.
• lastRun — the most recent match run (id, status of PROCESSING/COMPLETED/FAILED, and completedAt). It is null when the context has never run.
• readiness — activation-readiness summary (see below).
• next — the deterministic next setup action to take, or null when the context is ready (see below).

Readiness and the checklist

---

The readiness block reports whether the context satisfies every activation requirement:

{
  "ready": false,
  "missing": ["field_maps", "match_rules"]
}

missing holds stable slugs you can map to per-requirement checklist items. The possible values are:

• sources_left — the context needs at least one LEFT-side source.
• sources_right — the context needs at least one RIGHT-side source.
• field_maps — at least one source is unmapped: it has no field map and is not a self-mapped CAMT.053 source.
• match_rules — the context needs at least one match rule.
• fee_rules — the context enables fee normalization but has no fee rule. This requirement is conditional: it appears only when feeNormalization is set (NET or GROSS), and it mirrors the run precondition, which gates on fee rules — not fee schedules — being non-empty.

When a context is transitioned to ACTIVE before it is ready, the update is rejected with the generic configuration invalid-state 409. That response does not include the missing slugs. Re-read setup progress after the conflict and use readiness.missing to render the remaining setup guidance.

The next action

---

next turns readiness.missing into a concrete call. It is derived from missing[0] — the first unsatisfied requirement in the stable order above — and is null when the context is ready:

{
  "slug": "field_maps",
  "action": "add_field_map",
  "operationId": "createFieldMap",
  "method": "POST",
  "path": "/v1/contexts/{contextId}/sources/{sourceId}/field-maps",
  "requiredFields": ["mapping"],
  "forSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bank statement"
  }
}

• slug — the readiness slug this action satisfies.
• action — a stable semantic label you can key UI copy on.
• operationId, method, path — the endpoint to call to satisfy the requirement.
• requiredFields — the names of the fields that create request requires. They never carry values; you supply those.
• forSource — present only for the field_maps action, naming the first unmapped source so you can fill {sourceId} without a separate lookup.

The full slug-to-action table:

slug	action	Endpoint	requiredFields
sources_left	add_left_source	POST /v1/contexts/{contextId}/sources	name, type, side
sources_right	add_right_source	POST /v1/contexts/{contextId}/sources	name, type, side
field_maps	add_field_map	POST /v1/contexts/{contextId}/sources/{sourceId}/field-maps	mapping
match_rules	add_match_rule	POST /v1/contexts/{contextId}/rules	priority, type, config
fee_rules	add_fee_rule	POST /v1/contexts/{contextId}/fee-rules	side, feeScheduleId, name

Both source-side actions resolve to the same createSource operation — the side field is what distinguishes them.

How to use it during setup

---

1. Render the checklist. On each step of the wizard, GET setup-progress and use the counts (sources, fieldMaps, matchRules, schedules) to tick off completed items.
2. Drive the primary button from next. Instead of reimplementing the requirement order client-side, call the operation next names; re-read setup-progress afterwards to get the following action.
3. Gate the “Activate” button. Enable activation only when readiness.ready is true; otherwise list readiness.missing as the remaining steps.
4. Show run health. Once lastRun is present, surface its status and completedAt so operators can confirm the context is producing results.

Because the whole state comes from one call, you can poll this endpoint to keep the wizard live without orchestrating separate source, rule, and run reads.

Response codes

---

Status	Meaning
200	Setup progress returned
404	Context not found