Record a journey event
/journey-eventsRecords an investor's move to a step of the deal's workflow and returns it with a Location. kind: jump follows the main chain; floating_step records a floating step and needs PERM_CAN_MANAGE_TM_WORKFLOW or super admin (403). A forward jump records each step it passes; a jump back, or to the current step, removes later events and returns 200 with the target's event. Requirements and triggers run per new event (422, 409, 502). No webhook; staff and the investor are notified as notify says. DELETE /journey-events/{id} undoes a new event.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
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
- One of:
jump moves the investor to a step in the main chain. floating_step records a floating step outside it.
jump,floating_step The deal the journey is for.
The platform investor. Send this or external_investor_id, not both.
The external investor. Send this or investor_id, not both.
The step to move to. It must be on the deal's transaction workflow, and a floating step for floating_step.
The tranche of the deal to record the event in. Defaults to the deal's active tranche; a tranche from another deal returns 422.
Whether to tell staff who receive transaction notifications, the investor's CC list and key contact, and the investor, in-app and by email. Defaults to true for jump and false for floating_step, which reports funds received. A move onto a branching step or the current step tells nobody.
What the event records. Amounts are decimal strings and currency_code is ISO 4217; they update the investment. Keys must be fields of a step the move records, note, removal_data, historic_data, portfolio_unit_value or portfolio_total_units; others return 422.
{
"kind": "jump",
"deal_id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
"investor_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"to_step_id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
"event_data": {
"committed_amount": "250000.00",
"currency_code": "GBP"
}
}Responses
No event was recorded and the body is the event on the step. On the investor's current step, nothing changes and event_data is ignored. On an earlier step, the later steps' events are removed with their triggers reverted; the event's data is replaced, and its checks and triggers run again, only when event_data changes an amount or the step branches.
{
"data": {
"id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"kind": "jump",
"deal_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"investment_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"tranche_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"investor_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"external_investor_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"from_step_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"from_step_label": "string",
"to_step_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"to_step_label": "string",
"initial": true,
"event_data": {},
"created_at": "2026-06-12T10:00:00+00:00",
"updated_at": "2026-06-12T10:00:00+00:00"
}
}{
"data": {
"id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"kind": "jump",
"deal_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"investment_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"tranche_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"investor_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"external_investor_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"from_step_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"from_step_label": "string",
"to_step_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
"to_step_label": "string",
"initial": true,
"event_data": {},
"created_at": "2026-06-12T10:00:00+00:00",
"updated_at": "2026-06-12T10:00:00+00:00"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The workflow can't be run (conflict): the deal has no workflow; a step has a requirement or trigger core doesn't support; a requirement's or trigger's settings are delegated to the deal and the deal has none; a form trigger has no form, or its form no longer exists; a classification requirement lists no classifications; a webhook trigger has no webhook, or its webhook no longer exists; a document trigger has no template, its template or form no longer exists, the investor was not given the form on the step, or its DocuSign recipients can't be resolved; a document release trigger has no folder on the deal, or the investor is a team; a KYC trigger has no next step, or one that isn't on the workflow; a Portfolio trigger has no asset, its asset no longer exists or has a subscription type core doesn't support, the investor is a team, or the investor's profile has no name or email; a conditional branch uses a condition core doesn't support, has no branches, branches to a step that isn't on the workflow, or matches none of the investor's classifications; automatic progression loops back to a step, or runs past 10 steps; or a jump passes a step that branches, can't reach its step by following the workflow, or goes to a step alongside the investor's current one; or the investor has no event on the step a jump moves back to.
validation_failed, with every problem in details. The move is checked against the trailing requirements of the step being left (not for floating_step), the required fields of the step being entered, and that step's leading requirements. An unmet requirement is rule: step_requirement on to_step_id with the requirement's message. A missing required field is rule: required on event_data.<key>, and a key sent as null counts as present. A key the step doesn't record is rule: prohibited on event_data.<key>. Optional requirements are not enforced. A step that moves the investor to a chosen branch needs event_data.progress_to_step_id, a non-floating step on the deal's workflow; that move is checked the same way. A step that posts the investment to Portfolio needs a confirmed_amount above zero when one is sent, plus event_data.portfolio_total_units and event_data.portfolio_unit_value where the asset calls for them. An amount in a currency other than the investment's is rule: currency.
upstream_error: a service the workflow calls failed, either for a trigger (such as a webhook receiver refusing the call, attachments refusing a generated document or a folder grant, or Portfolio refusing an asset lookup or a transaction) or while Sumsub resets an expired proof of address. Nothing is written, and calls already made that can be undone are undone.
Examples
curl -X POST https://your-org-domain/kong/core/api/v2/journey-events\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"kind": "jump",
"deal_id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
"investor_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"to_step_id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
"event_data": {
"committed_amount": "250000.00",
"currency_code": "GBP"
}
}'