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, or list

• 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:

Command Line

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"
        }
      }'