ConnectCloud Developers

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:

{
  "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

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

View as Markdown · Interactive reference · OpenAPI