Workflows

Use workflows to automate multi-step processes

The Workflow Execution object

A Workflow Execution represents an instance of a workflow run triggered by your backend or frontend application. You can run workflows on a Transactionlink-hosted page, embed the form in your app, or execute them entirely in the background.

Use this object to initialize the flow, pass context, and retrieve completion status via webhooks or polling.

We recommend creating a new execution each time a user starts a workflow, to ensure that the flow is fresh and state is isolated for every attempt.

Attribute	Type	Description
workflowId	string (UUID)	Unique identifier for this workflow execution.
workspaceId	string (UUID)	ID of the workspace where the workflow is being run.
workflowDefinitionId	string (UUID)	ID of the predefined workflow definition, configured in the Transactionlink Dashboard.
parameters	object	Key-value map of input parameters used to dynamically influence the workflow logic. Values can be strings, numbers, booleans, or nested objects.
name	string	Name of the workflow definition (e.g., "KYC Verification - John Doe").
workflowDefinitionRevisionString	string	Version string of the workflow definition (e.g., rev-2025-04).
status	string (enum)	Current status of the workflow execution. Possible values: TIMEOUT RUNNING COMPLETED FAILED EXPIRED AWAITING
locale	string	Interface language (IETF tag), e.g., en, pl, de. If omitted, defaults to user’s browser language.
recordId	string (UUID)	External Record ID associated with the workflow execution.
token	string	Short-lived token used to initialize the embedded widget. Only returned when uiMode = embedded.
link	string (URL)	URL of the Transactionlink-hosted workflow page. Only returned when uiMode = hosted.
uiMode	string (enum)	UI mode that determines how the workflow is shown to the user: • hosted – shown on a separate Transactionlink-hosted page • embedded – embedded in your app • background – runs entirely in backend logic
expiresAt	string (ISO 8601 timestamp)	Expiration time of the workflow execution. Must be 30 min – 24 hrs in future. Defaults to 1 hour if omitted.

Run Workflow

post

Differences between versions: version 1 relies on caseId and is scheduled for deprecation, whereas version 2 uses recordId and no longer returns partyDetails.

Body

application/jsonapplication/json;version=2

caseIdstring · uuidRequired

Case identifier for which we want to initiate the workflow

workflowDefinitionIdstringRequired

ID of the workflow definition

Example: 3b2d8a4f-579f-4e2e-a51c-f859e532fe8c

parametersIdstringOptional

ID of the parameters used in workflow

Example: 4b6ffcb6-ab6d-44b9-b5ab-4b5147b0b302

Responses

200

Workflow has been run

application/jsonapplication/json;version=2

404

Workflow Definition Not Found

application/json

post

HTTPcURLJavaScriptPython

POST /workflows/run HTTP/1.1
Host: api.transactionlink.io
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "caseId": "11111111-2222-3333-4444-555555555555",
  "workflowDefinitionId": "3b2d8a4f-579f-4e2e-a51c-f859e532fe8c",
  "parametersId": "4b6ffcb6-ab6d-44b9-b5ab-4b5147b0b302"
}

application/jsonapplication/json;version=2

{
  "id": "e1413f5b-acb0-4995-919a-3fc60c9592c5",
  "caseId": "c3faa0ef-e83a-41e8-b178-9fd8e4b0ee81",
  "status": "COMPLETED"
}