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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/telesign:flow-builder-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.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.
contact:
name: Telesign Customer Support Team
email: support@telesign.com
servers:
- url: https://us-east-1.di-hub.telesign.com
tags:
- name: Flow Builder
paths:
/hubv2/model/flow/init-flow:
post:
summary: Initialize transactional flow
description: '> 📘 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:
| Field(s) | Situation |
| --- | --- |
| **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**. |
| **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. |
If a required parameter is missing **or** the key name doesn’t match, the response is:
```json
{
"data": null,
"error": {
"message": "Required fields missing: "
}
}
```
> 📘 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
| # | Content type | Rule |
| --- | --- | --- |
| 1 | Case-sensitive | `clientId`, `clientID`, and `CLIENTID` are three different parameters. |
| 2 | Free-form names | Letters, numbers, and underscores allowed (`segment`, `Segment1`, `customer_email`). Avoid spaces. |
| 3 | Primitive values | Accepts string, number, boolean. |
| 4 | One-to-one mapping | Every **required** parameter must appear in `dataToReplace`; optional parameters may be skipped. |
**Example 1 – ID lookup**
1. Create flow: Add a Request parameter called `idNumber`.
2. Call `/init-flow` with:
```json
{
"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:
```json
{
"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.'
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.
| Error Condition | error.message | Description |
| --- | --- | --- |
| 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
- 'null'
description: Contains the error information. When the request is successful, this value is null.
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).
| Error Condition | `error.message` | Description |
| --- | --- | --- |
| 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. |
| Missing required dynamic parameters | Required fields missing: <param1>, <param2>… | The flow was configured to expect certain parameters that were not supplied. |
| 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
- 'null'
description: Contains the results of the request. Since this is an error, this value is `null`.
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.
'
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
- 'null'
description: Contains the results of the request. Since this is an error, this value is `null`.
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.
'404':
description: '**Flow ID not found.** The flowId provided does not exist or does not belong to the authenticated account.
| Error Condition | error.message | Description |
| --- | --- | --- |
| Unknown flowId | This FlowId was not found | The supplied flowId does not exist. |'
content:
application/json:
schema:
type: object
properties:
data:
type:
- object
- 'null'
description: Contains the results of the request. Since this is an error, this value is `null`.
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.
| Error Condition | error.message | Description |
| --- | --- | --- |
| Internal error | Internal Server Error | Unexpected exception on the server side. |
'
content:
application/json:
schema:
type: object
properties:
data:
type:
- object
- 'null'
description: Contains the results of the request. Since this is an error, this value is `null`.
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
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token obtained in the authentication request (e.g., 'Bearer YOUR_ACCESS_TOKEN_HERE').
externalDocs:
description: Protect API Authentication - Get AccessToken
url: https://developer.telesign.com/enterprise/docs/get-started-with-docs
x-readme:
explorer-enabled: true
proxy-enabled: true