{"openapi":"3.0.0","info":{"title":"Flow Builder API","version":"2.0","description":"The Flow Builder solution is designed to streamline the creation, execution, and management of transactional flows. By leveraging business rules and data from both internal and external sources, the Flow Builder enables organizations to automate decision-making processes efficiently and securely.\n\n\n","contact":{"name":"Telesign Customer Support Team","email":"support@telesign.com"}},"externalDocs":{"description":"Protect API Authentication - Get AccessToken","url":"https://developer.telesign.com/enterprise/docs/get-started-with-docs"},"servers":[{"url":"https://us-east-1.di-hub.telesign.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token obtained in the authentication request (e.g., 'Bearer YOUR_ACCESS_TOKEN_HERE')."}}},"paths":{"/hubv2/model/flow/init-flow":{"post":{"summary":"Initialize transactional flow","description":"> 📘 NOTE:\n> \n> 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.\n\nThis 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.\n\n## General Requirements\n\n* **Authentication:** This authentication method is mandatory, to obtain a valid token from the authentication system, post that include it in all API requests.\n* **Encoding:** The API only accepts characters in UTF-8 Unicode format.\n* **Accepts:** application/json is the expected data format for the API.\n* **Responds with:** application/json is the data format for API responses.\n* **Required headers:**\n  * `Content-Type: application/json`\n  * `Authorization: Bearer [your-Access-token]`\n\n## How `dataToReplace` works\n\n`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).\n\n## Required versus optional parameters\n\nIn two situations, a parameter becomes required and will trigger a `400 – Missing Required Parameters` error if absent:\n\n| Field(s) | Situation |\n| --- | --- |\n| **Mail field / Phone field** | Select **one** existing parameter that holds the user’s e-mail or phone number. The Hub flags it as required for nodes such as **PhoneID**. |\n| **Advanced → Select required fields** | Multi-select listing **all** parameters in the flow. Any parameter you select here is required at runtime; un-selected parameters remain optional. |\n\nIf a required parameter is missing **or** the key name doesn’t match, the response is:\n\n```json\n{\n  \"data\": null,\n  \"error\": {\n    \"message\": \"Required fields missing: <parameterName>\"\n  }\n}\n```\n\n> 📘 NOTE:\n> \n> The comparison is case-sensitive (clientId ≠ ClientID). Parameters not flagged in either list above are optional and can be omitted without error.\n\n\n## Naming and value rules\n\n| # | Content type | Rule |\n| --- | --- | --- |\n| 1 | Case-sensitive | `clientId`, `clientID`, and `CLIENTID` are three different parameters. |\n| 2 | Free-form names | Letters, numbers, and underscores allowed (`segment`, `Segment1`, `customer_email`). Avoid spaces. |\n| 3 | Primitive values | Accepts string, number, boolean. |\n| 4 | One-to-one mapping | Every **required** parameter must appear in `dataToReplace`; optional parameters may be skipped. |\n\n**Example 1 – ID lookup**\n\n1. Create flow: Add a Request parameter called `idNumber`.\n2. Call `/init-flow` with:\n\n```json\n{\n  \"flowId\": \"…\",\n  \"dataToReplace\": {\n    \"idNumber\": \"90123456\"\n  }\n}\n```\n\n3. Result: The flow forwards `90123456` to a downstream personal-data service.\n\n**Example 2 – Customer segment routing**\n\n1. Create flow: Add a parameter called `segment`.\n2. Call `/init-flow` with:\n\n```json\n{\n  \"flowId\": \"…\",\n  \"dataToReplace\": {\n    \"segment\": \"GOLD\"\n  }\n}\n```\n\n3. Result: Branching rules route GOLD customers to the premium path.\n\n\n> 📘 NOTE:\n> \n> If you rename or delete a parameter in the flow designer, update your `dataToReplace` keys accordingly to avoid the 400 – Missing Required Parameters error.\n","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["flowId","dataToReplace"],"properties":{"flowId":{"type":"string","description":"Unique identifier of the flow created in the Transactional Hub."},"dataToReplace":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Dictionary of key → value pairs the flow will consume. Keys must match the names defined in Request parameters (case-sensitive). Values are primitive JSON types."}}},"examples":{"Full example":{"value":{"flowId":"18380c27-1d1c-4f79-a449-a7c8b12ddf62","dataToReplace":{"name":"Juan","cellphone":"11234567890","email":"juan.perez@example.com","age":28,"message":"Hello, this is an example"}}},"Id lookup":{"value":{"flowId":"…","dataToReplace":{"idNumber":"90123456"}}},"Segment routing":{"value":{"flowId":"…","dataToReplace":{"segment":"GOLD"}}}}}}},"responses":{"200":{"description":"**Success.** The request has been successfully processed, and the flow has been initialized.\n\n| Error Condition | error.message | Description |\n| --- | --- | --- |\n| Success | — | The request was processed successfully. A `pTracking` UUID is returned so you can trace the transaction. |","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","description":"Text describing the results of your request."},"pTracking":{"type":"string","description":"A unique identifier (UUID v4) that allows you to track a transaction. A UUID v4 is a 128-bit identifier that is randomly generated from pseudo-random numbers."}}},"error":{"type":"object","description":"Contains the error information. When the request is successful, this value is null.","nullable":true}}},"examples":{"Response":{"value":{"data":{"status":"success","pTracking":"802f22a7-c98c-43aa-9ac0-0a0060de8360"},"error":null}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"":{"type":"string"}}}}}},"400":{"description":"**Missing Required Parameters.** Missing required parameters or invalid body fields. The client must send both `flowId` (UUID v4) and `dataToReplace` (object).\n\n\n| Error Condition | `error.message` | Description |\n| --- | --- | --- |\n| Missing / invalid body fields | Request validation failed | One or more fields are missing or have the wrong type/format. See error.details for a per-field breakdown. |\n| Missing required dynamic parameters | Required fields missing: <param1>, <param2>… | The flow was configured to expect certain parameters that were not supplied. |\n| Invalid flow status | Invalid Flow | The supplied flowId exists, but its status does not allow this operation. |","content":{"application/json":{"examples":{"RequestValidationFailed":{"value":{"data":null,"error":{"message":"Request validation failed","details":{"flowId":{"message":"flowId must be a UUID v4"},"dataToReplace":{"message":"dataToReplace must be an object"}}}}},"Missing required dynamic parameters":{"value":{"data":null,"error":{"message":"Required fields missing: <parameters_names>"}}},"Invalid flow status":{"value":{"data":null,"error":{"message":"Invalid Flow"}}}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"Contains the results of the request. Since this is an error, this value is `null`.","nullable":true},"error":{"type":"object","description":"Provides details on why the request failed.","properties":{"message":{"type":"string","description":"A high-level, general description of the problem. It summarizes what went wrong with the overall request without providing specific details."},"details":{"type":"object","description":"Provides a specific, detailed report for each field that had an issue. This helps you identify exactly what needs to be fixed.","properties":{"flowId":{"type":"object","description":" The part of the report shows that the unique flow ID you submitted was not in the correct format.","properties":{"message":{"type":"string","description":"Text which describes the specific validation error for the flowId."}}},"dataToReplace":{"type":"object","description":"A specific report about why the information in the `dataToReplace` field was not in the expected format.\n","properties":{"message":{"type":"string","description":"This message indicates the specific reason why the information you provided in the dataToReplace field was not in the correct format or type."}}}}}}}}}}}},"401":{"description":"**Authentication issues.** The request failed because no authorization header provided, an incomplete header (e.g. `Bearer` without token), no authorization header provided, unsupported authorization method, invalid signature, or an expired token. \n\n| Error Condition | `error.message` | Description |\n| --- | --- | --- |\n| No Authorization header | No authorization header provided | Authentication header is completely absent. |\n| Bad header format | Authorization header format error | Header present but incomplete (e.g. Bearer without the token). |\n| Unsupported scheme | Unsupported authorization method | Scheme is not Bearer or Basic. |\n| Token failed validation | Error validating token | Token could not be parsed or verified. |\n| Token expired / not found | Invalid or expired token | Token is syntactically valid but no longer accepted. |","content":{"application/json":{"examples":{"No header provided":{"value":{"data":null,"error":{"message":"No authorization header provided"}}},"Incomplete header":{"value":{"data":null,"error":{"message":"Authorization header format error"}}},"Unsupported scheme":{"value":{"data":null,"error":{"message":"Unsupported authorization method"}}},"Invalid signature":{"value":{"data":null,"error":{"message":"Error validating token"}}},"Expired token":{"value":{"data":null,"error":{"message":"Invalid or expired token"}}}},"schema":{"type":"object","properties":{"data":{"type":"object","description":"Contains the results of the request. Since this is an error, this value is `null`.","nullable":true},"error":{"type":"object","description":"Provides details on why the request failed.\n","properties":{"message":{"type":"string","description":"A high-level, general description of the problem. It summarizes what went wrong with the overall request without providing specific details."}}}}}}}},"404":{"description":"**Flow ID not found.** The flowId provided does not exist or does not belong to the authenticated account.\n\n\n| Error Condition | error.message | Description |\n| --- | --- | --- |\n| Unknown flowId | This FlowId was not found | The supplied flowId does not exist. |","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Contains the results of the request. Since this is an error, this value is `null`.","nullable":true},"error":{"type":"object","description":"Provides details on why the request failed.","properties":{"message":{"type":"string","description":"A high-level, general description of the problem."}}}}},"examples":{"Flow ID not found":{"value":{"data":null,"error":{"message":"This FlowId was not found"}}}}}}},"500":{"description":"**Internal Server Error.** Unexpected exception on the server side.\n\n\n| Error Condition | error.message | Description |\n| --- | --- | --- |\n| Internal error | Internal Server Error | Unexpected exception on the server side. |\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Contains the results of the request. Since this is an error, this value is `null`.","nullable":true},"error":{"type":"object","description":"Provides details on why the request failed.","properties":{"message":{"type":"string","description":"A high-level, general description of the problem."}}}}},"examples":{"Internal server error":{"value":{"data":null,"error":{"message":"Internal Server Error"}}}}}}}},"operationId":"initializeTransactionalFlow","tags":["Flow Builder"]}}},"tags":[{"name":"Flow Builder"}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}