FlowGeneration

FlowGeneration is created to initiate the generation of a flow based on a specific configuration. The FlowGeneration resource encapsulates the configuration of the flow to be generated, including the flow type, parameters, and context. Once a flow generation is created, the generation of a flow is queued and will be processed by the system. When the flow is generated the status of a flow generation will be updated to finished.

Synchronous Flow Generation

In the sandbox environment we allow for synchronous flow generation. This means that the response to the POST request will wait until the flow is generated and return the finished FlowGeneration object containing the flowId. This is useful for development and testing purposes as it prevents you having to implement full webhook handling. To enable this feature you can add the query parameter ?sync=true to the POST request.

This feature is not available in the production environment.

Endpoints

• GET /flow-generations - Retrieves a list of all flow generation configurations.

• GET /flow-generations/{id} - Retrieves a specific flow generation configuration by ID.

• POST /flow-generations - Creates a new flow generation.

• DELETE /flow-generations/{id} - Deletes a specific flow generation by ID.'

Attributes

Field	Type	Description
flowType	String	The type of flow you want to generate. See flow-types
parameters	JSON Object	Specific parameters needed for the flow, including language, emoji usage, flow name, and various requirements.
context	JSON Object	Contextual information that defines the operational environment or requirements of the flow. Can be required or not depending on the flow.
flowId	UUID	Unique identifier of the flow.
status	String	Current status of the flow. The status can be queued, processing, finished.
cost	Integer	Cost associated with the flow.
createdAt	DateTime	The timestamp when the flow generation was created.
updatedAt	DateTime	The timestamp when the flow generation was last updated.

HTTP Methods

Field	GET	POST	PATCH
flowType	X	X
parameters	X	X
context	X	X
flowId	X
status	X
cost	X
createdAt	X
updatedAt	X

Required Fields for Creation (POST)

Field	Type	Example value
flowType	String	vacancy_application_flow
parameters	JSON Object	{ "language": "nl", "emojiUsage": "3", "flowName": "Driver", "knockoutRequirements": [ {"value": "Has drivers license B", "sessionField": "drivers_license"}, {"value": "Must be communicative", "sessionField": "communicative"} ], "preferredRequirements": [ {"value": "Lives in Amsterdam", "sessionField": "location"} ], "requiredFields": [ {"value": "firstName", "sessionField": "first_name"}, {"value": "email", "sessionField": "email"}, {"value": "phoneNumber", "sessionField": "phone"} ], "optionalFields": [ {"value": "address", "sessionField": "address"}, {"value": "linkedin", "sessionField": "linkedin"}, {"value": "portfolio", "sessionField": "portfolio"} ] }
context	JSON Object	{ "type": "text", "value": "Example vacancy text here." }

Example POST body

{
  "data": {
    "type": "flowGenerations",
    "attributes": {
      "flowType": "vacancy_application_flow",
      "parameters": {
        "language": "nl",
        "emojiUsage": "3",
        "flowName": "Driver",
        "knockoutRequirements": [
          {"value": "Has drivers license B", "sessionField": "drivers_license"},
          {"value": "Must be communicative", "sessionField": "communicative"}
        ],
        "preferredRequirements": [
          {"value": "Lives in Amsterdam", "sessionField": "location"}
        ],
        "requiredFields": [
          {"value": "firstName", "sessionField": "first_name"},
          {"value": "email", "sessionField": "email"},
          {"value": "phoneNumber", "sessionField": "phone"}
        ],
        "optionalFields": [
          {"value": "address", "sessionField": "address"},
          {"value": "linkedin", "sessionField": "linkedin"},
          {"value": "portfolio", "sessionField": "portfolio"}
        ]
      },
      "context": {
        "type": "text",
        "value": "Example vacancy text here."
      }
    }
  }
}

Example POST body with a V2 Appointment Step

{
  "data": {
    "type": "flowGenerations",
    "attributes": {
      "flowType": "vacancy_application_flow",
      "parameters": {
        "language": "nl",
        "emojiUsage": "3",
        "flowName": "Driver",
        "knockoutRequirements": [
          {"value": "Has drivers license B", "sessionField": "drivers_license"},
          {"value": "Must be communicative", "sessionField": "communicative"}
        ],
        "preferredRequirements": [
          {"value": "Lives in Amsterdam", "sessionField": "location"}
        ],
        "requiredFields": [
          {"value": "firstName", "sessionField": "first_name"},
          {"value": "email", "sessionField": "email"},
          {"value": "phoneNumber", "sessionField": "phone"}
        ],
        "optionalFields": [
          {"value": "address", "sessionField": "address"},
          {"value": "linkedin", "sessionField": "linkedin"},
          {"value": "portfolio", "sessionField": "portfolio"}
        ],
        "extraOptions": [
          {
            "value": "appointment",
            "language": "en",
            "options": {
              "version": 2,
              "scheduleIds": "1,2,3"
            }
          }
        ]
      },
      "context": {
        "type": "text",
        "value": "Example vacancy text here."
      }
    }
  }
}

Validation Errors

When a post request fails validation due to missing parameters, a structured error response is returned detailing the issues.

{
  "errors": [
    {"code": "unprocessable_entity", "status": "422", "title": "Validation Error", "detail": "Parameter knockoutRequirements can't be blank", "source": {"pointer": "/data/relationships/parameter"}},
    {"code": "unprocessable_entity", "status": "422", "title": "Validation Error", "detail": "Parameter requiredFields can't be blank", "source": {"pointer": "/data/relationships/parameter"}}
  ]
}

OpenAPI

Create a flow generation

post

Authorizations

Body

Responses

201

flow_generation created

401

access denied

422

requiredFields contains invalid fields.

post

HTTPcURLJavaScriptPython

POST /public/v2/flow-generations HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 172

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "flowId": "123e4567-e89b-12d3-a456-426614174000",
      "flowType": "text",
      "parameters": {},
      "context": {},
      "publicApiInitiated": true
    }
  }
}

No content

Retrieve all FlowGenerations

get

Authorizations

Responses

200

flow_generations found

application/vnd.api+json

401

access denied

get

HTTPcURLJavaScriptPython

GET /public/v2/flow-generations HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "type": "text",
      "attributes": {
        "createdAt": "2025-06-07T05:28:09.714Z",
        "updatedAt": "2025-06-07T05:28:09.714Z",
        "flowId": "123e4567-e89b-12d3-a456-426614174000",
        "flowType": "text",
        "parameters": {},
        "context": {},
        "status": "queued",
        "cost": 3
      }
    }
  ]
}

Retrieve a single flow_generation

get

Authorizations

Path parameters

idstringRequired

Responses

200

flow_generation found

application/vnd.api+json

401

access denied

404

FlowGeneration not found

get

HTTPcURLJavaScriptPython

GET /public/v2/flow-generations/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "createdAt": "2025-06-07T05:28:09.714Z",
      "updatedAt": "2025-06-07T05:28:09.714Z",
      "flowId": "123e4567-e89b-12d3-a456-426614174000",
      "flowType": "text",
      "parameters": {},
      "context": {},
      "status": "queued",
      "cost": 3
    }
  }
}

Destroy a FlowGeneration

delete

Authorizations

Path parameters

idstringRequired

Responses

204

flow_generation destroyed

401

access denied

404

FlowGeneration not found

delete

HTTPcURLJavaScriptPython

DELETE /public/v2/flow-generations/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*

No content