Parameters
Learn how to use parameters to pass additional information when creating a Workflow Execution.
Parameters are attributes you can provide when triggering a workflow execution. They're structured as key-value pairs and allow you to attach additional context or metadata from your own system. For example, you might store a user's unique identifier or a reference ID from your internal application.
Defining parameters
In the Dashboard, when creating or editing a workflow, you can define a set of expected parameters. For each parameter, you specify:
Key – how the parameter will be referenced in the workflow
Type – one of the supported types:
string
,number
,boolean
,object
, orlist
Optional/Required – whether the parameter must be provided when starting the workflow
Typical Use Cases
Use parameters in scenarios such as:
User Identification: You want to store internal user IDs (
userId
) to easily link workflow executions back to user records in your system.Tracking & Reconciliation: You're passing custom tracking identifiers, such as transaction IDs, order numbers, or reference IDs, to simplify reconciliation and auditing.
Dynamic Workflow Behavior: Your workflow requires dynamic behavior based on context, such as country codes, client types, or other metadata.
External References: You have external records stored in your database and want to reference them within your workflow executions for auditing or retrieval purposes.
Best Practices
Clear Naming: Use descriptive, concise, and self-explanatory keys (e.g.,
userId
,orderId
,transactionReference
).Security Considerations: Avoid including sensitive data such as passwords, tokens, or personally identifiable information directly in parameters. Parameters may be logged or audited.
External Data Storage: For larger payloads, prefer external storage solutions. Pass a reference ID or pointer to the external data instead.
Example Request
Here's an explicit example of how to include parameters in your POST request to initiate a workflow:
curl -X POST https://api.transactionlink.io/workflows \
-H "Content-Type: application/json" \
-d '{
"recordId": "6f1a8b43-0e69-4c27-b123-f715aa6a01ef",
"workflowDefinitionId": "9ac5e4b8-fd54-4df2-987d-215acc92ea43",
"expiresAt": "2025-12-01T23:59:59Z",
"uiMode": "EMBEDDED",
"locale": "en-US",
"parameters": {
"userId": "usr_123456789",
"transactionId": "txn_987654321",
"countryCode": "US",
"clientSegment": "enterprise",
"externalRecordReference": "ext_ref_4521abc123"
}
}'
Last updated
Was this helpful?