Create a KYC flow for a programme
/v1/kyc/flowsRequires an API client bearer token.
Creates a named KYC flow and everything it needs to be usable immediately, in ONE transaction: the flow registry row, its policy lineage at version 1, and a copy of the programme default flow's branding (copied regardless of `start_from`, with a fresh logo version). The flow is born PUBLISHED — selectable and draftable the moment this returns — and the response is the same `KycFlowSummary` row `GET /v1/kyc/flows` returns, ready to drop straight into the flows index. `start_from: 'default'` copies the default flow's currently active policy definition verbatim into the new lineage's version 1; `'blank'` starts from the platform baseline policy. `flow_key` is permanent (rename changes `display_name` only) and `'default'` is RESERVED — the constructive flow every programme already has cannot be created (400 `flow_key_reserved`). A key this programme already uses is a 409 `flow_exists`, which writes nothing and does NOT consume the Idempotency-Key: the same key may be retried with a different `flow_key`. Requires Idempotency-Key; an identical retry returns the SAME flow and does not create a second one. Requires the programme_admin role and shares `POST /v1/kyc/policy`'s tightest rate-limit class.
Parameters
Header parameters
| Name | Required | Description |
|---|---|---|
| Idempotency-Key | required | Client-chosen. An identical retry with the same key returns the stored response; reusing the key with a different payload returns 409. |
Request body
Example
curl -X POST https://api.rigid.fi/v1/kyc/flows \
-H "Authorization: Bearer $RIGID_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"programme_id": "uuid",
"flow_key": "string",
"display_name": "string",
"start_from": "default"
}'Responses
201The newly created flow, as one row of the flows index.
+ show properties− hide properties
+ show properties− hide properties
+ show properties− hide properties
+ show properties− hide properties
+ show properties− hide properties
400Validation error
401Authentication required
403Forbidden
409This programme already has a flow with this `flow_key` (code `flow_exists`), or the Idempotency-Key was reused with a different payload
429Too many policy writes from this caller — see Retry-After (shares POST /v1/kyc/policy's budget: creating a flow mints an immutable policy version row)
500Internal server error