Customer onboarding with KYC

In this tutorial, you build a customer onboarding process — a BPMN-driven app that collects personal data through multi-step forms, verifies the customer’s identity via an external KYC API, generates a welcome letter, and routes failed verifications to a manual review queue. What you will build:

A multi-step form that collects personal details, address, employment, and document uploads
A KYC verification integration that calls an external REST API via an integration workflow
An exclusive gateway that routes the process based on verification results
A document generation step that produces a personalized welcome letter
A manual review task assigned to compliance officers when KYC fails
An email notification sent upon successful onboarding
A timer boundary event for SLA tracking on the review task

Node types used: User Task, Send Message Task, Receive Message Task, Exclusive Gateway, Timer Boundary Event Patterns demonstrated: Multi-step form collection, REST API integration via workflows, conditional branching, document generation, task assignment, notification sending

Architecture overview

The process follows a collect-verify-decide pattern. Customer data is gathered through a series of user task nodes, sent to a KYC service for verification, and then routed based on the result. The main process orchestrates four form steps, delegates KYC verification to an integration workflow, and uses an exclusive gateway to branch into success or manual review paths.

Prerequisites

Before starting, make sure you have:

Access to a FlowX Designer workspace
The Documents Plugin deployed and configured (for document generation)
The Notifications Plugin deployed and configured (for email sending)
A document template named welcomeLetter created in Document Templates (HTML template with placeholders for customer name and date)
Familiarity with creating processes, user tasks, and actions in FlowX

If you do not have a real KYC service available, you can simulate one using a mock REST API endpoint (for example, a simple service that returns PASSED or FAILED based on predefined rules). The integration workflow calls this endpoint the same way it would call a production KYC provider.

Data model

Define the following keys in your process data model. All keys use camelCase and are nested under logical groups.

Key path	Type	Description
`customer.firstName`	String	Customer first name
`customer.lastName`	String	Customer last name
`customer.dateOfBirth`	String	Date of birth (ISO format)
`customer.nationalId`	String	National ID or passport number
`customer.email`	String	Email address
`customer.phone`	String	Phone number
`address.street`	String	Street address
`address.city`	String	City
`address.postalCode`	String	Postal code
`address.country`	String	Country (ISO 3166 code)
`employment.status`	String	`EMPLOYED`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED`
`employment.employer`	String	Employer name (if employed)
`employment.monthlyIncome`	Number	Monthly income in local currency
`employment.startDate`	String	Employment start date
`documents.identityDoc`	Object	Uploaded identity document reference
`documents.proofOfAddress`	Object	Uploaded proof of address reference
`kycResult`	Object	KYC verification response from external API
`kycResult.status`	String	`PASSED`, `FAILED`, or `REVIEW`
`kycResult.score`	Number	Risk score (0-100)
`kycResult.reasons`	Array	List of reasons if not passed
`reviewDecision`	String	Manual review outcome: `APPROVED` or `REJECTED`
`reviewNotes`	String	Notes from the compliance reviewer
`generatedDocs.welcomeLetter`	Object	Generated welcome letter document reference
`notificationResult`	Object	Email notification delivery result

Step 1: Create the process definition

Create a new process

In FlowX Designer, navigate to your project and create a new process definition named customerOnboarding.Set the platform to Web Only (or Omnichannel if you plan to support mobile).

Add swimlanes

Create two swimlanes:

Customer — for the user-facing form steps
BackOffice — for the manual review task (assigned to a compliance role)

This ensures the review task is routed to the right team while the customer interacts with the form steps.

For details on configuring swimlanes and role-based access, see the Swimlanes documentation.

Step 2: Build the data collection forms

Create four User Task nodes in the Customer swimlane, connected in sequence. Each node represents one step of the onboarding form.

User Task 1: Personal information

Node name: personalInfo Open the UI Designer and add a Card with a Form containing these fields:

Component	Label	Key	Validation
Input	First name	`customer.firstName`	Required
Input	Last name	`customer.lastName`	Required
Datepicker	Date of birth	`customer.dateOfBirth`	Required, must be 18+
Input	National ID	`customer.nationalId`	Required
Input	Email	`customer.email`	Required, email format
Input	Phone	`customer.phone`	Required

Add a Button labeled Next with an action of type Save Data to persist the form values.

User Task 2: Address details

Node name: addressInfo

Component	Label	Key	Validation
Input	Street address	`address.street`	Required
Input	City	`address.city`	Required
Input	Postal code	`address.postalCode`	Required
Select	Country	`address.country`	Required (populate from enumeration)

Use an enumeration for the country dropdown. Create an enumeration named countries with ISO 3166 country codes and labels.

Add Back and Next buttons. Set canGoBack: true on this node so the customer can return to the previous step.

User Task 3: Employment and income

Node name: employmentInfo

Component	Label	Key	Validation
Radio	Employment status	`employment.status`	Required
Input	Employer name	`employment.employer`	Required if EMPLOYED
Input	Monthly income	`employment.monthlyIncome`	Required, numeric
Datepicker	Start date	`employment.startDate`	Required if EMPLOYED

Use a conditional expression on the Employer and Start Date fields to show them only when employment.status is EMPLOYED or SELF_EMPLOYED.

User Task 4: Document upload

Node name: documentUpload

Component	Label	Key
File Upload	Identity document (passport or ID card)	`documents.identityDoc`
File Upload	Proof of address (utility bill or bank statement)	`documents.proofOfAddress`

Add a Submit button that triggers the process to move to the KYC verification step.

Uploaded files are stored via the Documents Plugin. Make sure the plugin is configured with an S3-compatible storage backend before testing this step.

Step 3: Set up the KYC verification integration

The KYC check is handled by an integration workflow that calls an external REST API. This keeps the BPMN process clean and the integration logic reusable.

Create the data source

Add a RESTful System data source

Navigate to Integrations > Data Sources and create a new data source:

Type: RESTful System
Name: KYC Provider
Code: kycProvider
Base URL: https://api.{your-kyc-provider}.com/v1
Authorization: Bearer Token (configure the token value using a Configuration Parameter Override so it differs per environment)

Define the verification endpoint

Under the data source, add an endpoint:

Method: POST
Path: /verify
Body type: JSON
Request body example:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "dateOfBirth": "1990-05-15",
  "nationalId": "AB1234567",
  "country": "GB"
}

Response example:

{
  "status": "PASSED",
  "score": 92,
  "reasons": [],
  "verificationId": "kyc-20260311-001"
}

Create the integration workflow

Create the workflow

Navigate to Integrations > Workflows and create a new workflow named kycVerification.

Add a REST Call node

Add a REST API Call node connected to the Start node. Configure it to use the kycProvider data source and the /verify endpoint.Map the input variables to the request body:

{
  "firstName": "${customer.firstName}",
  "lastName": "${customer.lastName}",
  "dateOfBirth": "${customer.dateOfBirth}",
  "nationalId": "${customer.nationalId}",
  "country": "${address.country}"
}

Add an End Flow node

Add an End Flow node after the REST Call. Set the body to pass the response back:

{
  "output": ${kycResponse}
}

For a detailed guide on building integration workflows, see the Integration Designer documentation.

Step 4: Trigger KYC from the BPMN process

Back in the customerOnboarding process, add a Send Message Task and a Receive Message Task after the documentUpload user task.

Send Message Task: Start KYC check

Node name: sendKycRequest Add an action:

Action type: Start Integration Workflow
Workflow: kycVerification
Input mapping:

{
  "customer": "${customer}",
  "address": "${address}"
}

Trigger: Automatic
Mandatory: Yes

Receive Message Task: Receive KYC result

Node name: receiveKycResult

Key Name: kycResult

The workflow output is captured at this key. Subsequent nodes can access kycResult.status, kycResult.score, and kycResult.reasons.

The process waits at the Receive Message Task until the integration workflow completes and returns its output. For details on this pattern, see Start Integration Workflow Action.

Step 5: Add the KYC decision gateway

Add an Exclusive Gateway node after the receiveKycResult node. Node name: kycDecision Configure two outgoing branches:

Branch	Condition (JavaScript)	Target
Passed	`kycResult.status === "PASSED"`	Go to document generation (success path)
Failed / Review	Default (else)	Go to manual review task

Using the default branch for the failure path ensures that any unexpected status value (not just FAILED) is routed to human review rather than slipping through.

For details on configuring exclusive gateways, see the Exclusive Gateway Node documentation.

Step 6: Build the success path

The success path generates a welcome letter and sends a confirmation email.

Generate the welcome letter

Add a Send Message Task and Receive Message Task pair for document generation.

Send Message Task: Generate welcome letter

Node name: sendGenerateWelcomeLetter Add a Kafka Send Action with:

Topic: ai.flowx.plugin.document.trigger.generate.html.v1
Message body:

{
  "documentList": [
    {
      "customId": "welcomeLetter",
      "templateName": "welcomeLetter",
      "language": "en",
      "data": {
        "customerName": "${customer.firstName} ${customer.lastName}",
        "currentDate": "${#now('yyyy-MM-dd')}",
        "accountReference": "${kycResult.verificationId}"
      },
      "includeBarcode": false
    }
  ]
}

The templateName must match a document template you created in Document Templates. Use the WYSIWYG editor to design the welcome letter with placeholders like {{customerName}} and {{currentDate}}. For details, see Generating documents from templates.

Receive Message Task: Receive letter result

Node name: receiveWelcomeLetter

Data stream topic: use the value from KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT (default: ai.flowx.engine.receive.plugin.document.generate.html.results.v1)
Key Name: generatedDocs.welcomeLetter

Send the confirmation email

Add another Send Message Task and Receive Message Task pair for notification.

Send Message Task: Send email

Node name: sendEmailNotification Add a Kafka Send Action with:

Topic: ai.flowx.plugin.notification.trigger.send.notification.v1
Message body:

{
  "templateName": "onboardingComplete",
  "channel": "email",
  "receivers": [
    {
      "email": "${customer.email}"
    }
  ],
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}",
    "subject": "Welcome - Your account is ready"
  }
}

Create the onboardingComplete notification template in the Notifications Plugin before testing. For configuration details, see the Notifications Plugin documentation.

Receive Message Task: Receive email confirmation

Node name: receiveEmailConfirmation

Data stream topic: use the value from KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT (default: ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1)
Key Name: notificationResult

After this node, add an End Event node to close the success path.

Step 7: Build the manual review path

When KYC fails or returns a REVIEW status, the process routes to a human reviewer.

User Task: Manual review

Node name: manualReview Place this node in the BackOffice swimlane. Open the UI Designer and create a review interface:

Component	Label	Key	Notes
Text	Customer name	`customer.firstName` + `customer.lastName`	Read-only display
Text	National ID	`customer.nationalId`	Read-only display
Text	KYC status	`kycResult.status`	Read-only display
Text	Risk score	`kycResult.score`	Read-only display
Text	Reasons	`kycResult.reasons`	Read-only list
Select	Decision	`reviewDecision`	Options: `APPROVED`, `REJECTED`
Input (textarea)	Notes	`reviewNotes`	Required

Add two buttons:

Approve — sets reviewDecision to APPROVED and advances
Reject — sets reviewDecision to REJECTED and advances

Enable Update Task Management on this node so the task appears in the Task Manager inbox for compliance officers. Assign the node to a swimlane with the appropriate role (for example, COMPLIANCE_REVIEWER).

Timer boundary event: SLA escalation

Attach a Timer Boundary Event to the manualReview node to enforce a 48-hour SLA.

Timer type: Duration
Duration: PT48H (ISO 8601 format — 48 hours)
Interrupting: No (non-interrupting — the review can still complete after escalation)

Connect the timer to a Send Message Task that sends an escalation notification:

{
  "templateName": "reviewEscalation",
  "channel": "email",
  "receivers": [
    {
      "email": "${escalation.managerEmail}"
    }
  ],
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}",
    "hoursOverdue": "48",
    "subject": "Overdue: KYC review pending for 48 hours"
  }
}

For details on timer configuration, see Timer Boundary Event and Timer Expressions.

Review decision gateway

Add a second Exclusive Gateway after the manualReview node. Node name: reviewDecisionGateway

Branch	Condition (JavaScript)	Target
Approved	`reviewDecision === "APPROVED"`	Go to document generation (same success path)
Rejected	Default (else)	Go to rejection End Event

For the Approved branch, connect to the same document generation and email notification nodes used in the success path (or duplicate them if your process layout requires separate paths). For the Rejected branch, add an End Event node labeled endRejected.

Step 8: Add a business rule for risk scoring (optional)

You can add a Business Rule Action on the receiveKycResult node to enrich the KYC response with custom logic before the gateway evaluates it. Action type: Business Rule Language: JavaScript

// Normalize the KYC result for downstream processing
var status = input.kycResult.status;
var score = input.kycResult.score;

// Override status based on custom score thresholds
if (status === "REVIEW" && score >= 75) {
  output.put("kycResult.status", "PASSED");
} else if (status === "REVIEW" && score < 50) {
  output.put("kycResult.status", "FAILED");
}

// Flag high-risk countries for additional review
var highRiskCountries = ["XX", "YY", "ZZ"];
if (highRiskCountries.indexOf(input.address.country) !== -1 && status === "PASSED") {
  output.put("kycResult.status", "REVIEW");
  output.put("kycResult.reasons", ["High-risk jurisdiction flagged for manual review"]);
}

Business rules execute synchronously within the process engine. Use them for lightweight data transformations and decision logic. For details, see Business Rule Action.

Step 9: Configure stages for Task Manager

Define stages to track progress in the Task Manager:

Stage name	Assigned to nodes
Data Collection	`personalInfo`, `addressInfo`, `employmentInfo`, `documentUpload`
KYC Verification	`sendKycRequest`, `receiveKycResult`
Manual Review	`manualReview`
Completion	`sendGenerateWelcomeLetter`, `sendEmailNotification`

Enable Update Task Management on the first user task node (personalInfo) and the manual review node (manualReview) so that process instances appear in the Task Manager with their current stage.

Testing

Test the happy path (KYC passes)

Start a new process instance and fill in all four form steps with valid data. Use a national ID that your mock KYC service recognizes as valid.Verify:

The KYC integration workflow completes and returns status: PASSED
The welcome letter is generated (check the document storage)
The confirmation email is sent to the customer email address
The process ends at the success End Event

{
  "customer": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": "1990-05-15",
    "nationalId": "AB1234567",
    "email": "jane.smith@example.com",
    "phone": "+44 7700 900000"
  },
  "address": {
    "street": "42 Oak Lane",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "employment": {
    "status": "EMPLOYED",
    "employer": "Acme Corp",
    "monthlyIncome": 4500,
    "startDate": "2020-03-01"
  }
}

Test the manual review path (KYC fails)

Start a new instance with data that triggers a FAILED or REVIEW KYC status.Verify:

The process routes to the manualReview user task
The task appears in the Task Manager for the BackOffice swimlane
Approving the review generates the welcome letter and sends the email
Rejecting the review ends the process at the rejection End Event

Test SLA escalation

Start a manual review scenario and let the 48-hour timer expire (for testing, temporarily change the duration to PT1M — one minute).Verify:

The escalation email is sent to the configured manager address
The review task remains active (non-interrupting timer)
The reviewer can still approve or reject after escalation

Test form navigation

Verify that the Back button on each form step returns the user to the previous step without losing entered data.Verify that required field validations prevent advancing to the next step when fields are empty.

What you learned

In this tutorial, you built a complete customer onboarding process that demonstrates several core FlowX capabilities:

Multi-step forms — using sequential User Task nodes with form components to collect structured data across multiple screens
Integration workflows — delegating external API calls (KYC verification) to reusable integration workflows triggered via the Start Integration Workflow action
Conditional routing — using Exclusive Gateway nodes with JavaScript conditions to branch process logic based on data values
Document generation — using the Documents Plugin with Kafka Send/Receive Message Tasks to generate documents from HTML templates
Notifications — using the Notifications Plugin to send email confirmations
Task assignment — using swimlanes and the Task Management plugin to route manual review tasks to specific roles
SLA tracking — using Timer Boundary Events to enforce and escalate overdue tasks
Business rules — using JavaScript business rules to enrich and transform data within the process

Next steps

Process definitions

Deep-dive into process configuration options

Integration Designer

Build more integration workflows for external systems

Task Management

Configure task routing and assignment rules

Mortgage advisor chatbot

Build a conversational AI app as a companion to this BPMN tutorial

Config-time agents

Agent Builder

Using agents

Tutorials

AI Patterns

​Architecture overview

​Prerequisites

​Data model

​Step 1: Create the process definition

​Step 2: Build the data collection forms

​User Task 1: Personal information

​User Task 2: Address details

​User Task 3: Employment and income

​User Task 4: Document upload

​Step 3: Set up the KYC verification integration

​Create the data source

​Create the integration workflow

​Step 4: Trigger KYC from the BPMN process

​Send Message Task: Start KYC check

​Receive Message Task: Receive KYC result

​Step 5: Add the KYC decision gateway

​Step 6: Build the success path

​Generate the welcome letter

​Send Message Task: Generate welcome letter

​Receive Message Task: Receive letter result

​Send the confirmation email

​Send Message Task: Send email

​Receive Message Task: Receive email confirmation

​Step 7: Build the manual review path

​User Task: Manual review

​Timer boundary event: SLA escalation

​Review decision gateway

​Step 8: Add a business rule for risk scoring (optional)

​Step 9: Configure stages for Task Manager

​Testing

​What you learned

​Next steps

Process definitions

Integration Designer

Task Management

Mortgage advisor chatbot

Architecture overview

Prerequisites

Data model

Step 1: Create the process definition

Step 2: Build the data collection forms

User Task 1: Personal information

User Task 2: Address details

User Task 3: Employment and income

User Task 4: Document upload

Step 3: Set up the KYC verification integration

Create the data source

Create the integration workflow

Step 4: Trigger KYC from the BPMN process

Send Message Task: Start KYC check

Receive Message Task: Receive KYC result

Step 5: Add the KYC decision gateway

Step 6: Build the success path

Generate the welcome letter

Send Message Task: Generate welcome letter

Receive Message Task: Receive letter result

Send the confirmation email

Send Message Task: Send email

Receive Message Task: Receive email confirmation

Step 7: Build the manual review path

User Task: Manual review

Timer boundary event: SLA escalation

Review decision gateway

Step 8: Add a business rule for risk scoring (optional)

Step 9: Configure stages for Task Manager

Testing

What you learned

Next steps