> For the complete documentation index, see [llms.txt](https://docs.transactionlink.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.transactionlink.io/docs/transactionlink-api/api-reference/workflows.md).

# Workflows

## 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.

{% hint style="info" %}
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.
{% endhint %}

## Initialise a new workflow execution

> Initialise a new workflow execution. Requires \`can\_run\` permission on the workflow definition.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]},{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."},"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Legacy JWT Bearer token — deprecated in favor of organization tokens (tot_). Still supported for backwards compatibility."}},"schemas":{"InitialiseWorkflowRequest":{"title":"InitialiseWorkflowRequest","required":["locale","parameters","workflowDefinitionId"],"type":"object","properties":{"workflowDefinitionId":{"type":"string","description":"Identifier of the workflow definition to execute"},"locale":{"type":"string","description":"Locale for the workflow execution, e.g., 'en', 'fr'"},"parameters":{"type":"object","description":"Key-value pairs of parameters required for the workflow execution"},"expiresAt":{"type":"string","description":"Optional expiration date-time for the workflow execution in ISO 8601 format. Must be between 30 minutes and 30 days from the current time","nullable":true},"recordId":{"type":"uuid","description":"Optional recordId this workflow refers to","nullable":true}}},"InitialiseWorkflowBackgroundResponse":{"title":"InitialiseWorkflowBackgroundResponse","required":["executionType","executionVersion","expiresAt","id","locale","name","origin","parameters","revision","status","uiOptions","workflowDefinitionId","workspaceId"],"type":"object","properties":{"workflowDefinitionId":{"type":"string","description":"Identifier of the workflow definition being executed"},"executionType":{"type":"string","description":"Type of execution"},"uiOptions":{"type":"object","description":"UI options for the workflow execution"},"locale":{"type":"string","description":"Locale used for the workflow execution"},"expiresAt":{"type":"string","description":"Expiration date-time of the workflow execution in ISO 8601 format, if set"},"revision":{"type":"string","description":"Revision of the workflow definition"},"name":{"type":"string","description":"Name of the workflow execution"},"id":{"type":"string","description":"Unique identifier of the workflow execution"},"parameters":{"type":"object","description":"Parameters used for the workflow execution"},"executionVersion":{"type":"number","description":"Version of the execution"},"status":{"type":"string","description":"Current status of the workflow execution"},"workspaceId":{"type":"string","description":"Identifier of the workspace where the workflow is executed"},"recordId":{"type":"uuid","description":"Identifier of the recordId that the workflow is referring to"},"origin":{"$ref":"#/components/schemas/OriginDto"}}},"OriginDto":{"title":"OriginDto","type":"object","description":"Origin information for workflow execution","required":["type"],"properties":{"type":{"type":"string","enum":["API","USER","WORKFLOW"],"description":"Type of origin"}},"discriminator":{"propertyName":"type","mapping":{"API":"#/components/schemas/ApiOriginDto","USER":"#/components/schemas/UserOriginDto","WORKFLOW":"#/components/schemas/WorkflowOriginDto"}}},"InitialiseWorkflowInteractiveResponse":{"title":"InitialiseWorkflowInteractiveResponse","required":["executionType","executionVersion","expiresAt","id","locale","name","parameters","revision","status","uiOptions","token","link","workflowDefinitionId","workspaceId","origin"],"type":"object","properties":{"workflowDefinitionId":{"type":"string","description":"Identifier of the workflow definition being executed"},"executionType":{"type":"string","description":"Type of execution"},"link":{"type":"string","description":"Link to access the workflow execution","nullable":true},"uiOptions":{"type":"object","description":"UI options for the workflow execution"},"locale":{"type":"string","description":"Locale used for the workflow execution"},"expiresAt":{"type":"string","description":"Expiration date-time of the workflow execution in ISO 8601 format, if set"},"token":{"type":"string","description":"Token for accessing the workflow execution","nullable":true},"revision":{"type":"string","description":"Revision of the workflow definition"},"name":{"type":"string","description":"Name of the workflow execution"},"id":{"type":"string","description":"Unique identifier of the workflow execution"},"parameters":{"type":"object","description":"Parameters used for the workflow execution"},"executionVersion":{"type":"number","description":"Version of the execution"},"status":{"type":"string","description":"Current status of the workflow execution"},"workspaceId":{"type":"string","description":"Identifier of the workspace where the workflow is executed"},"recordId":{"type":"uuid","description":"Identifier of the recordId that the workflow is referring to"},"origin":{"$ref":"#/components/schemas/OriginDto"}}},"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workflows":{"post":{"tags":["Workflows"],"summary":"Initialise a new workflow execution","description":"Initialise a new workflow execution. Requires `can_run` permission on the workflow definition.","operationId":"initialise-workflow","parameters":[{"name":"Authorization","in":"header","description":"Organization token (`tot_`) — preferred method, or legacy Bearer JWT token. Pass the `tot_` token directly without Bearer prefix; use `Bearer <jwt>` for legacy JWT auth.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"Content type of the request - application/json","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/InitialiseWorkflowRequest"}}}},"responses":{"200":{"description":"200","headers":{"Content-Type":{"description":"Content type of the response - application/json","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InitialiseWorkflowBackgroundResponse"},{"$ref":"#/components/schemas/InitialiseWorkflowInteractiveResponse"}]}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Find a workflow execution by its ID

> Find a workflow execution by its ID. Requires \`can\_view\_workspace\` permission on the workspace.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]},{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."},"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Legacy JWT Bearer token — deprecated in favor of organization tokens (tot_). Still supported for backwards compatibility."}},"schemas":{"FindWorkflowResponse":{"title":"FindWorkflowResponse","required":["executionType","executionVersion","expiresAt","id","locale","name","origin","parameters","revision","status","uiOptions","workflowDefinitionId","workspaceId"],"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the workflow execution"},"workspaceId":{"type":"string","format":"uuid","description":"Identifier of the workspace where the workflow is executed"},"workflowDefinitionId":{"type":"string","format":"uuid","description":"Identifier of the workflow definition being executed"},"parameters":{"type":"object","description":"Parameters used for the workflow execution"},"name":{"type":"string","description":"Name of the workflow execution"},"revision":{"type":"string","description":"Revision of the workflow definition"},"status":{"type":"string","description":"Current status of the workflow execution. One of: INITIALISED, CREATED, RUNNING, COMPLETED, AWAITING, FAILED, TIMEOUT, TERMINATED, EXPIRED, CANCELLED, PAUSED","enum":["INITIALISED","CREATED","RUNNING","COMPLETED","AWAITING","FAILED","TIMEOUT","TERMINATED","EXPIRED","CANCELLED","PAUSED"]},"locale":{"type":"string","description":"Locale used for the workflow execution"},"expiresAt":{"type":"string","format":"date-time","description":"Expiration date-time of the workflow execution in ISO 8601 format, if set"},"uiOptions":{"type":"object","description":"UI options for the workflow execution"},"executionType":{"type":"string","description":"Type of execution"},"executionVersion":{"type":"number","description":"Version of the execution"},"token":{"type":"string","description":"Token for accessing the workflow execution","nullable":true},"link":{"type":"string","description":"Link to access the workflow execution","nullable":true},"recordId":{"type":"string","format":"uuid","description":"Identifier of the record that the workflow is referring to","nullable":true},"origin":{"$ref":"#/components/schemas/OriginDto"}}},"OriginDto":{"title":"OriginDto","type":"object","description":"Origin information for workflow execution","required":["type"],"properties":{"type":{"type":"string","enum":["API","USER","WORKFLOW"],"description":"Type of origin"}},"discriminator":{"propertyName":"type","mapping":{"API":"#/components/schemas/ApiOriginDto","USER":"#/components/schemas/UserOriginDto","WORKFLOW":"#/components/schemas/WorkflowOriginDto"}}},"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workflows/{workflowId}":{"get":{"tags":["Workflows"],"summary":"Find a workflow execution by its ID","description":"Find a workflow execution by its ID. Requires `can_view_workspace` permission on the workspace.","operationId":"find-workflow","parameters":[{"name":"workflowId","in":"path","description":"Unique identifier of the workflow execution to retrieve","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`) — preferred method, or legacy Bearer JWT token. Pass the `tot_` token directly without Bearer prefix; use `Bearer <jwt>` for legacy JWT auth.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","headers":{"Content-Type":{"description":"Content type of the response - application/json","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/FindWorkflowResponse"}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Cancel a running workflow execution

> Cancel a running workflow execution. Requires \`can\_view\_workspace\` permission on the workspace.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]},{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."},"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Legacy JWT Bearer token — deprecated in favor of organization tokens (tot_). Still supported for backwards compatibility."}},"schemas":{"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workflows/{workflowId}/cancel":{"post":{"tags":["Workflows"],"summary":"Cancel a running workflow execution","description":"Cancel a running workflow execution. Requires `can_view_workspace` permission on the workspace.","operationId":"cancel-workflow","parameters":[{"name":"workflowId","in":"path","description":"Unique identifier of the workflow execution to cancel","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`) — preferred method, or legacy Bearer JWT token. Pass the `tot_` token directly without Bearer prefix; use `Bearer <jwt>` for legacy JWT auth.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"200"},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get the result of a workflow execution

> Returns the JSON result payload produced by a workflow execution. The result is retrieved from storage and reflects the final output of the workflow run. Requires \`can\_view\_workspace\` permission on the workspace.\
> \
> For result payloads exceeding 9 MB the response will not contain the full JSON body. Instead a redirect object is returned with a single \`$redirect\` key whose value is a pre-signed S3 URL valid for 5 minutes. The client must follow that URL with an unauthenticated GET request to retrieve the full payload directly from storage.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"}],"security":[{"organizationToken":[]},{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"organizationToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Organization API token (tot_) — preferred authentication method. Pass the token directly without Bearer prefix."},"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Legacy JWT Bearer token — deprecated in favor of organization tokens (tot_). Still supported for backwards compatibility."}},"schemas":{"ErrorResponse":{"required":["errors","fingerprint"],"type":"object","properties":{"fingerprint":{"type":"string","description":"Unique identifier for this error instance"},"errors":{"type":"array","description":"List of error details","items":{"required":["code","message"],"properties":{"code":{"type":"string","description":"Error code representing the type of error"},"message":{"type":"string","description":"Error message providing more details about the error"}}}}}}}},"paths":{"/workflows/{workflowId}/result":{"get":{"tags":["Workflows"],"summary":"Get the result of a workflow execution","description":"Returns the JSON result payload produced by a workflow execution. The result is retrieved from storage and reflects the final output of the workflow run. Requires `can_view_workspace` permission on the workspace.\n\nFor result payloads exceeding 9 MB the response will not contain the full JSON body. Instead a redirect object is returned with a single `$redirect` key whose value is a pre-signed S3 URL valid for 5 minutes. The client must follow that URL with an unauthenticated GET request to retrieve the full payload directly from storage.","operationId":"get-workflow-result","parameters":[{"name":"workflowId","in":"path","description":"Unique identifier of the workflow execution","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","description":"Organization token (`tot_`) — preferred method, or legacy Bearer JWT token. Pass the `tot_` token directly without Bearer prefix; use `Bearer <jwt>` for legacy JWT auth.","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow result payload. For results larger than 9 MB a redirect object is returned instead of the full payload — see the `get-workflow-result-redirect` example.","headers":{"Content-Type":{"description":"Content type of the response - application/json","style":"simple","explode":false,"schema":{"type":"string"}}},"content":{"application/json;charset=UTF-8":{"schema":{"oneOf":[{"type":"object","description":"Arbitrary JSON object representing the result produced by the workflow execution. Returned when the payload is 9 MB or smaller. The structure depends on the workflow definition."},{"type":"object","description":"Redirect object returned when the result payload exceeds 9 MB. The client must perform an unauthenticated GET request to the `$redirect` URL to download the full payload directly from storage. The URL expires after 5 minutes.","required":["$redirect"],"properties":{"$redirect":{"type":"string","format":"uri","description":"Pre-signed S3 URL valid for 5 minutes."}}}]}}}},"400":{"description":"Bad Request – invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized – JWT token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden – insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found – workflow execution does not exist or result is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error – unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.transactionlink.io/docs/transactionlink-api/api-reference/workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.