Initialize transactional flow

📘

NOTE:

Select regional availability. This feature is currently available for customers with end users in select countries. To find out if this feature is available in your region, contact a Telesign expert. This product is available for full-service accounts only.

This endpoint starts a transactional flow inside the Flow Builder. The request must contain a valid flowId and a dataToReplace object whose keys match the parameters defined when the flow was created.

General Requirements

• Authentication: This authentication method is mandatory, to obtain a valid token from the authentication system, post that include it in all API requests.
• Encoding: The API only accepts characters in UTF-8 Unicode format.
• Accepts: application/json is the expected data format for the API.
• Responds with: application/json is the data format for API responses.
• Required headers:
  • Content-Type: application/json
  • Authorization: Bearer [your-Access-token]

How dataToReplace works

dataToReplace is the payload that feeds the flow with the dynamic values your business logic needs. Each entry is a simple key → value pair. Key must be identical (case, spelling, numbers, underscores) to the parameter name configured under Request parameters. Value is a primitive JSON value (string, number, or boolean).

Required versus optional parameters

In two situations, a parameter becomes required and will trigger a 400 – Missing Required Parameters error if absent:

If a required parameter is missing or the key name doesn’t match, the response is:

{
  "data": null,
  "error": {
    "message": "Required fields missing: <parameterName>"
  }
}

📘

NOTE:

The comparison is case-sensitive (clientId ≠ ClientID). Parameters not flagged in either list above are optional and can be omitted without error.

Naming and value rules

Example 1 – ID lookup

1. Create flow: Add a Request parameter called idNumber.
2. Call /init-flow with:

{
  "flowId": "…",
  "dataToReplace": {
    "idNumber": "90123456"
  }
}

3. Result: The flow forwards 90123456 to a downstream personal-data service.

Example 2 – Customer segment routing

1. Create flow: Add a parameter called segment.
2. Call /init-flow with:

{
  "flowId": "…",
  "dataToReplace": {
    "segment": "GOLD"
  }
}

3. Result: Branching rules route GOLD customers to the premium path.

📘

NOTE:

If you rename or delete a parameter in the flow designer, update your dataToReplace keys accordingly to avoid the 400 – Missing Required Parameters error.