BPMN processes

If a form uses a BPMN diagram, its tasks move through the diagram blocks rather than through steps. In the API, diagram blocks are called nodes, and the arrows between them are called flows.

A task's position in the process is described by tokens. A token is a marker placed on a diagram node that shows where the task currently is and what it's waiting for. A task can have several tokens at once: for example, after an AND gateway, each parallel branch gets its own token. When the branches merge, their tokens complete, and a new token continues along the diagram.

The API methods described in this section let you:

• find out which nodes a task is at and whose action it's waiting for;
• see how a comment moved a task along the diagram;
• approve a task at a specific node, resume a suspended process, or move a token manually;
• get the description of a form's BPMN diagram and the list of its versions;
• find tasks in the form register that are at specific nodes.

• GET/forms/{form-id}/bpmnGet the list of BPMN diagram versions of a form
• GET/forms/{form-id}/bpmn/{bpmn-version}Get a BPMN diagram version of a form

BPMN fields in the form description

The GET /forms and GET /forms/{form-id} methods return two additional fields in the form description:

{
  "id": 1204,
  "name": "Payment request",
  "use_bpmn_for_new_tasks": true,
  "bpmn_version": 3
}

BPMN task fields

For tasks based on a BPMN diagram, the GET /tasks/{task-id} method returns additional fields. Tasks that follow regular routing don't have these fields.

The bpmn_tokens element

GET https://api.pyrus.com/v4/tasks/91827364

{
  "task": {
    "id": 91827364,
    "text": "Payment request for invoice No. 4417",
    "form_id": 1204,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 12,
        "node_name": "Legal approval",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 4471,
          "first_name": "Mary",
          "last_name": "Smith"
        }
      },
      {
        "token_id": 2,
        "node_id": 18,
        "node_name": "Wait 3 business days",
        "node_type": "Timer",
        "status": "Waiting",
        "event_type": "Timer",
        "event_time": "2026-09-05T09:00:00Z"
      }
    ]
    // ...
  }
}

In this example, the task is in two parallel branches at once: in one, it's waiting for legal approval, and in the other, for a timer to fire.

BPMN fields in task comments

If a comment moved a task along the diagram, the comment contains the bpmn_transitions array. If the comment didn't move any tokens, the field is not returned.

The bpmn_transitions element

If an element contains only token_id, the comment completed this token, and the token no longer exists. Tokens that the comment created and immediately completed are not included in the array.

{
  "id": 55510293,
  "text": "Approved",
  "approval_choice": "approved",
  "bpmn_transitions": [
    { "token_id": 1 },
    { "token_id": 2 },
    { "token_id": 7, "node_id": 24, "node_name": "Payment" }
  ]
}

In this example, tokens 1 and 2 completed at the merge gateway, and token 7 continued along the diagram in their place.

Actions on BPMN tasks

The POST /tasks/{task-id}/comments method accepts additional parameters for tasks based on a BPMN diagram. All of them are optional.

Approving at a specific node

If a task has split into parallel branches and the user's action is awaited at several nodes at once, specify the node you're acting at in bpmn_node_id.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "No objections",
  "approval_choice": "approved",
  "bpmn_node_id": 12
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 20,
        "node_name": "Accounting review",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Johnson"
        }
      },
      {
        "token_id": 2,
        "node_id": 18,
        "node_name": "Wait 3 business days",
        "node_type": "Timer",
        "status": "Waiting",
        "event_type": "Timer",
        "event_time": "2026-09-05T09:00:00Z"
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510294,
        "text": "No objections",
        "approval_choice": "approved",
        "bpmn_transitions": [
          { "token_id": 1, "node_id": 20, "node_name": "Accounting review" }
        ]
      }
    ]
    // ...
  }
}

Resuming after an error

If a token was suspended due to an error ("status": "Suspended", and the task has "bpmn_suspended": true), fix the cause and resume processing. The token continues from the same node.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "Bot access granted, resuming",
  "bpmn_resume_processing": true
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 3,
        "node_id": 15,
        "node_name": "Upload invoice",
        "node_type": "Activity",
        "status": "Active"
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510295,
        "text": "Bot access granted, resuming"
      }
    ]
    // ...
  }
}

Moving tokens manually

You can move a token to another node, bypassing the routing conditions. You can move several tokens in one comment.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "Returning for revision",
  "bpmn_token_moves": [
    { "token_id": 1, "node_id": 8 }
  ]
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 8,
        "node_name": "Prepare request",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Johnson"
        }
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510296,
        "text": "Returning for revision",
        "bpmn_transitions": [
          { "token_id": 1, "node_id": 8, "node_name": "Prepare request" }
        ]
      }
    ]
    // ...
  }
}

curl -X POST \
  'https://api.pyrus.com/v4/tasks/91827364/comments' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Returning for revision",
    "bpmn_token_moves": [
      { "token_id": 1, "node_id": 8 }
    ]
}'

Filtering the form register by diagram nodes

The GET /forms/{form-id}/register method accepts two additional parameters for forms with a BPMN diagram. You can combine them with other register filters.

GET request example:

GET https://api.pyrus.com/v4/forms/1204/register?bpmn_nodes=12,18

The same as a POST request, with the parameters in the request body:

{
  "bpmn_nodes": [12, 18],
  "bpmn_suspended": false
}

Nodes in the list are combined with OR: it's enough for a token to be at any of them. If you specify the ID of a node that doesn't exist, you won't get an error, but the result will be empty.

GET /forms/{form-id}/bpmn

This method returns the list of BPMN diagram versions of a form. It's available to anyone with access to the form.

GET https://api.pyrus.com/v4/forms/1204/bpmn

{
  "form_id": 1204,
  "active_bpmn_version": 3,
  "versions": [
    {
      "bpmn_version": 4,
      "description": "Draft with legal review",
      "create_date": "2026-09-20T08:15:00Z",
      "author": {
        "id": 4471,
        "first_name": "Mary",
        "last_name": "Smith",
        "type": "user"
      }
    },
    {
      "bpmn_version": 3,
      "create_date": "2026-08-01T10:00:00Z"
    }
  ]
}

curl -X GET \
  'https://api.pyrus.com/v4/forms/1204/bpmn' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Response fields

GET /forms/{form-id}/bpmn/{bpmn-version}

This method returns the description of the specified BPMN diagram version of a form: nodes, flows between them, field visibility conditions, and text frames. It's available to anyone with access to the form.

Every form always has version 0: until it's saved, it's returned empty. A deleted version is returned too, with the delete_date field. Empty arrays are not included in the response.

GET https://api.pyrus.com/v4/forms/1204/bpmn/3

{
  "form_id": 1204,
  "bpmn_version": 3,
  "active_bpmn_version": 3,
  "create_date": "2026-08-01T10:00:00Z",
  "active_task_nodes": [12],
  "nodes": [
    {
      "id": 1,
      "node_type": "Start",
      "position": { "x": 40, "y": 200 },
      "flows": [ { "id": 1, "to_node_id": 12 } ]
    },
    {
      "id": 12,
      "node_type": "Activity",
      "description": "Legal approval",
      "participant": {
        "person": {
          "id": 4471,
          "first_name": "Mary",
          "last_name": "Smith",
          "type": "user"
        }
      },
      "actions": ["Approve", "Reject"],
      "position": { "x": 240, "y": 200 },
      "flows": [ { "id": 2, "to_node_id": 2 } ]
    },
    {
      "id": 2,
      "node_type": "Finish",
      "position": { "x": 440, "y": 200 }
    }
  ],
  "field_visibility_conditions": [
    {
      "field_id": 7,
      "condition": { "field_id": 5, "condition_type": 3 }
    }
  ]
}

curl -X GET \
  'https://api.pyrus.com/v4/forms/1204/bpmn/3' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Response fields

The nodes element

The format is the same for the nodes and deleted_nodes arrays.

The participant element

The flows element

The format is the same for the flows and deleted_flows arrays.

The timer element

The subprocess_configuration element

The format is the same as for subprocess settings in the form description.

The condition element

The format is the same as for routing conditions in the form description.

Enumeration values

Token status (status)

Node type (node_type)

Learn more about diagram blocks in BPMN workflow.

Awaited event (event_type)

Error codes