# 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

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"},{"url":"https://api.sandbox.transactionlink.io","description":"Sandbox"}],"security":[{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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","operationId":"initialise-workflow","parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication","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

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"},{"url":"https://api.sandbox.transactionlink.io","description":"Sandbox"}],"security":[{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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","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":"Bearer token for authentication","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

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"},{"url":"https://api.sandbox.transactionlink.io","description":"Sandbox"}],"security":[{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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","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":"Bearer token for authentication","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.

```json
{"openapi":"3.0.1","info":{"title":"TransactionLink API","version":"v3"},"servers":[{"url":"https://api.transactionlink.io","description":"Production"},{"url":"https://api.sandbox.transactionlink.io","description":"Sandbox"}],"security":[{"bearerAuthJWT":[]}],"components":{"securitySchemes":{"bearerAuthJWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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.","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":"Bearer token for authentication","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Workflow result payload","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":{"type":"object","description":"Arbitrary JSON object representing the result produced by the workflow execution. The structure depends on the workflow definition."}}}},"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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.