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 tenantsteps(array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names anothername(string, required): Unique within the blueprint; referenced bynextSteps[].stepstepType(string, required):UserStep(a person decides) orSystemStep(the engine decides) (one ofUserStep,SystemStep)action(string): Outcome when the workflow ends after this step:approve→ APPROVED,reject→ REJECTED (German synonyms accepted), else COMPLETEDallowInquiry(boolean): The assignee may ask another person (inquiry)fields(array of Field): Fields shown in a user stepgroup(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 stepnotificationEmail(string): E-mail address notified about this stepnotifyAssigneesByEmail(boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps onlynotifyAssigneesByTeams(boolean): Notify the assignees in their personal Teams chat; user steps onlyteamsChannel(string): Comms webhook channel id notified about this step (seeGET /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 oftransaction)condition(string): Optional expr condition over the transaction data; false ends the start asTRIGGER_NOT_MATCHEDnextStep(NextStep)color(string): Button color of a user step transitioncondition(string): System steps: expr condition, ordefaulticon(string): Button icon of a user step transitionlabel(string): Button label of a user step transitionstep(string): Name of the target step
statuses(array of string): Trade statuses that start the workflowtransactionTypes(array of string): Trade transaction type codes (active in trade)
active(boolean): Only active blueprints start workflows; missing means activeinquiryWebhookUrl(string): Webhook (JSON) notified about inquiries and their answers;********keeps the stored URLoverviewField1(OverviewField)label(string): Column labelname(string): Transaction field shown in task lists
overviewField2(OverviewField)label(string): Column labelname(string): Transaction field shown in task lists
updatedAt(string (date-time), read-only): Last modification of the stored blueprintversion(integer (int64)): Informational; set to 1 when 0 on save
claimedAt(string (date-time)): When the task was claimed; omitted if unclaimedclaimedBy(string): E-mail of the person working on the task, empty if unclaimedcurrentStep(Step | null): Null once the workflow has endedcustomerId(TenantRef)customerId(string): Customer numbertenantName(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 runningguid(string (uuid)): Instance idhistory(array of HistoryEntry): Append-only history, oldest firstaction(string): Free text, e.g.Step completed,CLAIMED,UNCLAIMED,FORCE_PULLED,NOTE,CANCELLED,Rückfrage gestelltactor(string): E-mail of the person, orSYSTEMbranch(string):regularorinquirychanges(ChangeSetDiff): What trade changed, with old valuesadded(array of LineSnapshot): Lines added by duplicatingchangeSetId(string): Id of the applied change set (instance:revision:content hash)deleted(array of LineSnapshot): Lines deleted, with their old valuesheader(array of FieldChange): Changed transaction fieldslines(array of object): Changed fields of existing lineschanges(array of FieldChange): Changed fields of the linelineId(string): Trade line idposition(integer): Position of the line in the transaction
totals(object): Transaction totals before and after the changesnew(Totals)old(Totals)
color(string): Color of the chosen transition buttoncomment(string): Comment, note text or inquiry answergroup(string): HR group UUID of the stepicon(string): Icon of the chosen transition buttonnextStep(string): Name of the step the transition led tostepName(string): Step the entry belongs to (START/ENDfor the start and end of the workflow)timestamp(string (date-time)): When it happeneduser(string): E-mail of the person the step was assigned to
lastRetryAt(string (date-time)): Last automatic retry; omitted if noneobjectNumber(string): Transaction numberobjectType(string): Object type of the triggerretryCount(integer): Attempts of a pending trade start or write-backrevision(integer (int64)): Optimistic-lock counterstartTime(string (date-time)): When the instance startedtransactionId(string (uuid)): Trade transaction idworkflowState(WorkflowState): (one ofOPEN,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"