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
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
flowType
X
X
parameters
X
X
context
X
X
flowId
X
status
X
cost
X
createdAt
X
updatedAt
X
Required Fields for Creation (POST)
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"}
{"value": "Work permit?", "sessionField": "ats_field:connexys:work_permit"}
],
"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",
// To dynamically assign schedule IDs during the creation of the FlowRun, use the variable below instead of the scheduleIds.
// "scheduleMode": "custom"
"askDayNL": "Super, {{session.first_name}}! Tijd om kennis te maken. Plan snel een afspraak " \
"in op een moment dat jou past. De afspraak duurt ongeveer {{session.schedule.appointment_duration}} minuten 🗓️",
"askDayEN": "Great, {{session.first_name}}! Time to get to know each other. Quickly schedule " \
"an appointment at a time that suits you. " \
"The appointment will take about {{session.schedule.appointment_duration}} minutes 🗓️",
"askSlotNL": "Top! Kies nu nog een tijdstip dat jou het beste uitkomt 🕒",
"askSlotEN": "Great! Now choose a time that suits you best 🕒",
"noSlotNL": "Helaas, er zijn geen beschikbare tijden meer op deze dag.",
"noSlotEN": "Unfortunately, there are no available times left on this day.",
"confirmSlotMessageNL": "We hebben {{session._selectedAppointmentSlot.date_time_string}} " \
"voor je genoteerd. Klopt dit en ben je dan beschikbaar?",
"confirmSlotMessageEN": "We have noted {{session._selectedAppointmentSlot.date_time_string}} for " \
"you. Is this correct and are you available?",
"denyConfirmMessageNL": "Begrepen! Laten we een nieuw moment kiezen!",
"denyConfirmMessageEN": "Understood! Let's pick a new moment!",
}
}
]
},
"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
flow_generation created
No content
access denied
requiredFields contains invalid fields.
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
flow_generations found
access denied
GET /public/v2/flow-generations HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "text",
"type": "text",
"attributes": {
"createdAt": "2025-09-15T15:01:55.044Z",
"updatedAt": "2025-09-15T15:01:55.044Z",
"flowId": "123e4567-e89b-12d3-a456-426614174000",
"flowType": "text",
"parameters": {},
"context": {},
"status": "queued",
"cost": 3
}
}
]
}flow_generation found
access denied
FlowGeneration not found
GET /public/v2/flow-generations/{id} HTTP/1.1
Host: {defaulthost}
Authorization: YOUR_API_KEY
Accept: */*
{
"data": {
"id": "text",
"type": "text",
"attributes": {
"createdAt": "2025-09-15T15:01:55.044Z",
"updatedAt": "2025-09-15T15:01:55.044Z",
"flowId": "123e4567-e89b-12d3-a456-426614174000",
"flowType": "text",
"parameters": {},
"context": {},
"status": "queued",
"cost": 3
}
}
}Last updated