Skip to main content
PUT
Replace a workflow

Authorizations

​
Authorization
string
header
required

Authorization: Api-Key <application_api_key> (legacy X-Api-Key also accepted).

Headers

​
If-Match
string

Expected revision (takes precedence over body revision).

Path Parameters

​
workflowId
string
required
Pattern: ^idvw_[0-9a-f]{24}$

Body

application/json
​
name
string
required
Required string length: 1 - 120
​
steps
object[]
required
Required array length: 1 - 10 elements
​
description
string
Maximum string length: 500
​
profile_kind
enum<string>

Profile-kind scope (KYB). Absent -> both. A scoped workflow only mints sessions for a matching profile (400 idv_workflow_profile_kind_mismatch otherwise).

Available options:
individual,
organization,
both
​
theme_id
string | null

Must reference a non-archived theme in the caller's scope (400 idv_theme_not_found / idv_theme_archived otherwise). null/absent = use the workspace default theme.

Pattern: ^idvt_[0-9a-f]{24}$
​
status
enum<string>

Create only: draft (default) or active; archived is rejected. PUT rejects it (use /activate and /archive).

Available options:
draft,
active
​
is_default
boolean

Create only (PUT rejects it; use POST .../default).

​
retention_days
integer
default:60
deprecated

DEPRECATED single-horizon alias for pii_retention_days. Supplying only this field is understood as asking for all four components at this value: the control it belonged to was documented as governing both sensitive fields and capture artifacts, so fanning it out cannot retain less than the caller intended. This is a FULL REPLACE: a component omitted from the request is NOT preserved from the stored workflow. It resolves to retention_days if that is supplied, and to its own default otherwise, so an editor must send all four explicitly to avoid resetting a component it did not mean to change. Omitting every retention field is not the legacy 60: each component takes its own default (biometrics 90, id images 365, documents 1825, PII 2555). Values outside 30..365 are rejected even though each component accepts up to 2555: the alias keeps its original bounds so an older build never misreads a longer horizon.

Required range: 30 <= x <= 365
​
assessment_prompt_instructions
string

Additional workflow-admin instructions for the review agent. Use for stricter or wider flagging behavior before deterministic controls exist; empty/omitted means no extra guidance.

Maximum string length: 4000
​
privacy_contact_email

Required before the workflow can be activated or created as active.

Maximum string length: 254
​
profile_update_enabled
boolean

Automatic profile-write opt-in (default false).

​
auto_approve_questionnaire_only
boolean

Explicit approval policy for workflows consisting only of questionnaire steps, including optional steps. Default false.

​
iframe_enabled
boolean

Enable iframe embedding for future sessions. Default false.

​
allowed_frame_origins
string[]

HTTPS parent origins. Use an exact origin or leftmost wildcard, for example https://example.com or https://*.example.com.

Maximum array length: 20
Maximum string length: 253
​
flag_settings
object

Sparse per-code review overrides. A code ABSENT from the map is ENABLED (default-true). Keys are validated against the known configurable fraud-flag taxonomy: an unknown key -> 400 idv_flag_code_unknown. Deterministic service-enforced policy codes such as id_type_not_allowed cannot be disabled and return idv_flag_code_not_configurable.

​
revision
integer

Replace only: the CAS expectation (or use If-Match).

​
supported_features
enum<string>[]

Request-only editor capability assertions. Required when creating or replacing a workflow that contains a listed conditional question or typed response-field feature, and when replacing a workflow that already contains one. typed_response_fields_v1 is required if any stored or incoming response field has an explicit answer_type, including text. An old full-replace editor receives 409 idv_workflow_editor_capability_required before persistence; omitted fields are not implicitly merged. Untyped legacy writes remain unchanged. retention_schedules_v1 asserts the client renders and preserves all four per-component retention schedules; it is required on REPLACE when the stored schedule is not representable by the deprecated retention_days alias (i.e. not uniform and inside its 30..365 clamp) AND the write changes it. Retention create is never gated. This prevents older full-replace editors from silently removing rules they do not understand or shortening a schedule they cannot render. workflow_security_and_questionnaire_approval_v1 is required on REPLACE when iframe_enabled, allowed_frame_origins, or auto_approve_questionnaire_only differs from the stored workflow. Include this assertion only if your editor renders and preserves all three settings. conditional_steps_v1 is required when creating or replacing a workflow with any step visible_when, and when replacing a workflow that already has one.

Maximum array length: 16
Available options:
conditional_question_requirements_v1,
conditional_question_visibility_v1,
typed_response_fields_v1,
retention_schedules_v1,
workflow_security_and_questionnaire_approval_v1,
conditional_steps_v1
​
biometrics_retention_days
integer
default:90

Retention of liveness captures AND the cross-session biometric templates derived from them, in days. Copied onto sessions at create, so later workflow edits affect only future sessions. Like every component, the workflow owner may set up to seven years (2555 days); the 90-day default is the recommended setting, and a shorter regional limit (for example Quebec's one year) is the configuring tenant's responsibility.

Required range: 30 <= x <= 2555
​
id_images_retention_days
integer
default:365

Retention of identity-document captures (id_front / id_back) in days.

Required range: 30 <= x <= 2555
​
documents_retention_days
integer
default:1825

Retention of consumer-uploaded supporting documents in days.

Required range: 30 <= x <= 2555
​
pii_retention_days
integer
default:2555

Retention of the sensitive fields on a session (subject reference, questionnaire answers, capture and invite credentials, OCR fields, profile-mismatch details) in days. This is what the deprecated retention_days field has always governed.

Required range: 30 <= x <= 2555

Response

Replaced

​
data
object
required

Tenant/workspace-scoped, versioned workflow object. (Distinct from the legacy Workflow PRESET enum above.) The cycle-2 inline branding block is REMOVED; presentation lives on Theme objects referenced by theme_id.