## Get a workflow instance (tenant:access)

`GET /api/workflow/v1/instances/{instanceId}`

Module: Workflow · operationId: `getInstance` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Instance, webhook URLs redacted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `blueprint` (Blueprint): A workflow definition. In responses, set webhook URLs are replaced by `********`.
  - `id` (string, required): Free identifier, unique per tenant
  - `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
    - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
    - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
    - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
    - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
    - `fields` (array of Field): Fields shown in a user step
    - `group` (string): HR group UUID the user step is assigned to (required for user steps)
    - `lines` (LineActions)
    - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `notificationEmail` (string): E-mail address notified about this step
    - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
    - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
    - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
    - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
    - `user` (string): E-mail of a person the user step is additionally assigned to
  - `trigger` (Trigger, required)
    - `objectType` (string, required): The only supported object type (one of `transaction`)
    - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
    - `nextStep` (NextStep)
      - `color` (string): Button color of a user step transition
      - `condition` (string): System steps: expr condition, or `default`
      - `icon` (string): Button icon of a user step transition
      - `label` (string): Button label of a user step transition
      - `step` (string): Name of the target step
    - `statuses` (array of string): Trade statuses that start the workflow
    - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
  - `active` (boolean): Only active blueprints start workflows; missing means active
  - `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
  - `overviewField1` (OverviewField)
    - `label` (string): Column label
    - `name` (string): Transaction field shown in task lists
  - `overviewField2` (OverviewField)
    - `label` (string): Column label
    - `name` (string): Transaction field shown in task lists
  - `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
  - `version` (integer (int64)): Informational; set to 1 when 0 on save
- `claimedAt` (string (date-time)): When the task was claimed; omitted if unclaimed
- `claimedBy` (string): E-mail of the person working on the task, empty if unclaimed
- `currentStep` (Step | null): Null once the workflow has ended
- `customerId` (TenantRef)
  - `customerId` (string): Customer number
  - `tenantName` (string): Tenant name
- `data` (object): Transaction data at start, start metadata (`blueprintId`, `objectNumber`, `initialNote`, …), workflow-local input and open inquiry keys (`inquiry_to`, `inquiry_text`, …)
- `endTime` (string (date-time)): When the instance ended; omitted while running
- `guid` (string (uuid)): Instance id
- `history` (array of HistoryEntry): Append-only history, oldest first
  - `action` (string): Free text, e.g. `Step completed`, `CLAIMED`, `UNCLAIMED`, `FORCE_PULLED`, `NOTE`, `CANCELLED`, `Rückfrage gestellt`
  - `actor` (string): E-mail of the person, or `SYSTEM`
  - `branch` (string): `regular` or `inquiry`
  - `changes` (ChangeSetDiff): What trade changed, with old values
    - `added` (array of LineSnapshot): Lines added by duplicating
    - `changeSetId` (string): Id of the applied change set (instance:revision:content hash)
    - `deleted` (array of LineSnapshot): Lines deleted, with their old values
    - `header` (array of FieldChange): Changed transaction fields
    - `lines` (array of object): Changed fields of existing lines
      - `changes` (array of FieldChange): Changed fields of the line
      - `lineId` (string): Trade line id
      - `position` (integer): Position of the line in the transaction
    - `totals` (object): Transaction totals before and after the changes
      - `new` (Totals)
      - `old` (Totals)
  - `color` (string): Color of the chosen transition button
  - `comment` (string): Comment, note text or inquiry answer
  - `group` (string): HR group UUID of the step
  - `icon` (string): Icon of the chosen transition button
  - `nextStep` (string): Name of the step the transition led to
  - `stepName` (string): Step the entry belongs to (`START`/`END` for the start and end of the workflow)
  - `timestamp` (string (date-time)): When it happened
  - `user` (string): E-mail of the person the step was assigned to
- `lastRetryAt` (string (date-time)): Last automatic retry; omitted if none
- `objectNumber` (string): Transaction number
- `objectType` (string): Object type of the trigger
- `retryCount` (integer): Attempts of a pending trade start or write-back
- `revision` (integer (int64)): Optimistic-lock counter
- `startTime` (string (date-time)): When the instance started
- `transactionId` (string (uuid)): Trade transaction id
- `workflowState` (WorkflowState): (one of `OPEN`, `RETRYING_SYNC`, `APPROVED`, `REJECTED`, `COMPLETED`, `CANCELLED`, `TRIGGER_NOT_MATCHED`, `TECHNICALLY_FAILED`)

Example 200 answer:

```json
{
  "blueprint": {
    "active": true,
    "id": "er-freigabe",
    "overviewField1": {
      "label": "Lieferant",
      "name": "partnerCompany"
    },
    "overviewField2": {
      "label": "Brutto",
      "name": "grossTotal"
    },
    "steps": [
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "name": "freigabe",
        "nextSteps": [
          {
            "color": "success",
            "icon": "i-lucide-check-circle",
            "label": "Freigeben",
            "step": "freigegeben"
          },
          {
            "color": "warning",
            "icon": "i-lucide-undo-2",
            "label": "Zurück zur Kontierung",
            "step": "kontierung"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "stepType": "UserStep"
      },
      {
        "action": "approve",
        "name": "freigegeben",
        "stepType": "SystemStep"
      },
      {
        "action": "reject",
        "name": "abgelehnt",
        "stepType": "SystemStep"
      }
    ],
    "trigger": {
      "nextStep": {
        "step": "kontierung"
      },
      "objectType": "transaction",
      "statuses": [
        "MATCHED"
      ],
      "transactionTypes": [
        "INBOUND_INVOICE"
      ]
    },
    "updatedAt": "2026-10-14T13:22:05Z",
    "version": 3
  },
  "claimedAt": "2026-11-17T09:05:40Z",
  "claimedBy": "christina.adler@muster-it.example",
  "currentStep": {
    "allowInquiry": true,
    "fields": [
      {
        "label": "Eingangsnr.",
        "name": "transactionNumber"
      },
      {
        "label": "Rechnungsnummer",
        "name": "externalTransactionNumber"
      },
      {
        "label": "Lieferant",
        "name": "partnerCompany"
      },
      {
        "editable": true,
        "label": "Fällig am",
        "name": "dueDate"
      },
      {
        "label": "Brutto",
        "name": "grossTotal"
      },
      {
        "label": "Bezeichnung",
        "name": "lines.name"
      },
      {
        "editable": true,
        "label": "Kostenstelle",
        "name": "lines.lineData.costCenter",
        "required": true
      },
      {
        "label": "Menge",
        "name": "lines.quantity"
      }
    ],
    "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
    "lines": {
      "allowDelete": true,
      "allowDuplicate": true
    },
    "name": "kontierung",
    "nextSteps": [
      {
        "color": "primary",
        "icon": "i-lucide-arrow-right",
        "label": "Weiter zur Freigabe",
        "step": "freigabe"
      },
      {
        "color": "error",
        "icon": "i-lucide-x-circle",
        "label": "Ablehnen",
        "step": "abgelehnt"
      }
    ],
    "notifyAssigneesByEmail": true,
    "stepType": "UserStep"
  },
  "customerId": {
    "customerId": "99999",
    "tenantName": "DEMO"
  },
  "data": {
    "blueprintId": "er-freigabe",
    "externalTransactionNumber": "RE-482117",
    "grossTotal": 6911.52,
    "netTotal": 5808,
    "objectNumber": "ER-2026-00042",
    "partnerCompany": "Nordlicht IT-Distribution GmbH",
    "transactionNumber": "ER-2026-00042"
  },
  "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
  "history": [
    {
      "action": "Workflow started",
      "actor": "SYSTEM",
      "nextStep": "kontierung",
      "stepName": "START",
      "timestamp": "2026-11-17T08:41:12Z"
    },
    {
      "action": "CLAIMED",
      "actor": "christina.adler@muster-it.example",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:05:40Z"
    }
  ],
  "objectNumber": "ER-2026-00042",
  "objectType": "transaction",
  "retryCount": 0,
  "revision": 2,
  "startTime": "2026-11-17T08:41:12Z",
  "transactionId": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
  "workflowState": "OPEN"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/instances/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
