Create an onboarding flow

POST/onboarding-flows

Creates a draft onboarding flow and returns it with a Location. name is required; expiry_type, mode_type and user_types default to twelve_month, continuous and investor. The flow starts with one form, its start form. Add more with POST /onboarding-flows/{onboarding_flow_id}/forms, then draw the routes with PATCH /onboarding-flows/{id}. dry_run shows the result without saving it. Emits onboarding_flow.created and sends no email. DELETE /onboarding-flows/{id} undoes it.

Query parameters

dry_runboolean#
Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

Idempotency-Keystring#
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · OnboardingFlowCreate

namestringRequired#
The flow's display name. Names need not be unique.
expiry_typestring | null#
How often a respondent completes the flow again: daily, one_month, three_month, six_month, twelve_month or never_expire. Defaults to twelve_month.
One of: daily, one_month, three_month, six_month, twelve_month, never_expire
mode_typestring | null#
continuous lets a respondent change answers at any time; versioned keeps each completion as it was. Defaults to continuous.
One of: continuous, versioned
user_typesarray | null#
The user types the flow can onboard: investor, advisor or both. Defaults to investor.
One of: investor, advisor

{
  "name": "Investor suitability",
  "expiry_type": "twelve_month",
  "mode_type": "continuous",
  "user_types": [
    "investor"
  ]
}

Responses

201

The onboarding flow was created.

OnboardingFlow

{
  "data": {
    "id": "48e0c1a6-6f3b-4d44-9d49-0a5a0b8f2d11",
    "name": "Investor suitability",
    "status": "draft",
    "expiry_type": "twelve_month",
    "mode_type": "continuous",
    "user_types": [
      "investor"
    ],
    "routes": [
      {
        "from_form_id": "0b6c7c0e-1f0a-4b6c-8d0e-5f0f4a7a3c21",
        "to_form_id": "6d8f3a52-9a41-4d6c-b7a1-2c9e5d1b7f33",
        "condition_sets": [
          {
            "condition_type": "AND",
            "condition_value": null,
            "conditions": [
              {
                "form_field_id": "2f1d9a77-3c1e-4e85-a0b3-7d6c4e8b9a55",
                "operator": "=",
                "value": "yes"
              }
            ],
            "custom_conditions": []
          },
          {
            "condition_type": "OTHER",
            "condition_value": null,
            "conditions": [],
            "custom_conditions": []
          }
        ]
      }
    ],
    "definition": null,
    "form_count": 2,
    "start_form_id": "0b6c7c0e-1f0a-4b6c-8d0e-5f0f4a7a3c21",
    "created_at": "2026-11-08T10:30:00Z",
    "updated_at": "2026-11-08T10:30:00Z"
  }
}

401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error

403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error

422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/onboarding-flows\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "name": "Investor suitability",
  "expiry_type": "twelve_month",
  "mode_type": "continuous",
  "user_types": [
    "investor"
  ]
}'