Workflow API: Triggering Approvals Programmatically

Most workflows are started by users in the UI. But you can also start and advance them via API — useful when integrating an external trigger (ERP, scheduled job, IoT event).

Start a workflow

curl https://yourtenant.papyrus.io/api/v1/workflows/start \
  -X POST \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "wt_invoice_approval",
    "documentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "context": {
      "submittedBy": "user_abc123",
      "urgency": "normal",
      "comment": "Quarterly payment to Acme Ltd"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "instanceId": "wi_8a3b9c2d",
    "templateId": "wt_invoice_approval",
    "status": "Running",
    "currentNodeId": "approval_finance_manager",
    "currentApprovers": ["user_def456"],
    "slaDeadline": "2026-05-14T14:32:11Z"
  }
}

Query workflow state

curl https://yourtenant.papyrus.io/api/v1/workflows/instances/wi_8a3b9c2d \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT"

Approve / reject via API

If your integration includes an approval UI of its own (e.g., a Slack bot that posts approval cards), advance the workflow:

curl https://yourtenant.papyrus.io/api/v1/workflows/instances/wi_8a3b9c2d/advance \
  -X POST \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "actorUserId": "user_def456",
    "comment": "Approved per Q2 budget"
  }'

Actions: approve, reject, requestChanges, delegate. Rejection and request-changes require comment.

Listing my approvals (user-context)

For a user-context OAuth token, list the user's pending tasks:

curl https://yourtenant.papyrus.io/api/v1/workflows/tasks/me \
  -H "Authorization: Bearer $USER_TOKEN" -H "X-Tenant-Id: $TENANT"

Listing all pending tasks (admin-context)

With an API key holding workflows:read scope, you can list across the tenant:

curl "https://yourtenant.papyrus.io/api/v1/workflows/tasks?status=Pending&assigneeId=user_def456" \
  -H "Authorization: Bearer $KEY" -H "X-Tenant-Id: $TENANT"

Webhook integration

Subscribing to workflow.* webhook events is often cleaner than polling. Combine: start workflows via API, react to completion via webhook.

// Express.js handler
app.post('/webhooks/papyrus', (req, res) => {
  verifySignature(req.headers['x-papyrus-signature'], req.rawBody, webhookSecret);
  const event = req.body;

  switch (event.type) {
    case 'workflow.completed':
      handleWorkflowDone(event.data.instanceId, event.data.outcome);
      break;
    case 'workflow.task.assigned':
      notifyAssignee(event.data.assigneeId, event.data.taskId);
      break;
  }

  res.status(200).end();
});