> ## Documentation Index > Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt > Use this file to discover all available pages before exploring further. # Make a workflow the scope default > Atomically clears the previous default in the tenant/workspace and promotes this workflow. Enforced in Mongo by a partial unique index (at most one default per scope) plus a bounded clear-then-promote CAS loop; a swap that cannot settle returns 409. 409 idv_workflow_archived for archived workflows. The default is APPLIED at session create only while active. ## OpenAPI ````yaml /api-reference/idv-svc.json post /workflows/{workflowId}/default openapi: 3.1.0 info: title: Minerva IDV API version: 1.0.0-draft description: >- Customer API for identity verification. Create verification sessions for profiles, deliver invites, track capture progress, and read review outcomes. For the end-to-end flow, see the [IDV Integration Guide](/api-reference/idv-integration-guide). Reviewer-safe responses never expose storage keys, checksums, wrapped keys, encryption context, raw OCR, or raw model output. Decrypted personal data is available only on `GET /sessions/{sessionId}/data`, to an authenticated in-scope principal, with fail-closed auditing. servers: - url: https://api.gominerva.com/idv/v1 description: The production API server for Minerva identity verification security: [] tags: - name: sessions description: >- Verification sessions and invite delivery (application or dashboard authentication). - name: capture description: End-user capture flow (session or invite credentials). - name: review description: Review decisions and audited structured-data access. - name: workflows description: Workflow configuration for verification sessions. - name: themes description: Branding themes and managed logo assets. paths: /workflows/{workflowId}/default: post: tags: - workflows summary: Make a workflow the scope default description: > Atomically clears the previous default in the tenant/workspace and promotes this workflow. Enforced in Mongo by a partial unique index (at most one default per scope) plus a bounded clear-then-promote CAS loop; a swap that cannot settle returns 409. 409 idv_workflow_archived for archived workflows. The default is APPLIED at session create only while active. parameters: - $ref: '#/components/parameters/WorkflowId' responses: '200': description: The (now default) workflow content: application/json: schema: $ref: '#/components/schemas/WorkflowResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' security: - applicationApiKey: [] - dashboardUserToken: [] components: parameters: WorkflowId: name: workflowId in: path required: true schema: type: string pattern: ^idvw_[0-9a-f]{24}$ schemas: WorkflowResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WorkflowObject' WorkflowObject: type: object description: > 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`. required: - workflow_id - tenant_id - workspace_id - name - profile_kind - steps - status - theme_id - is_default - retention_days - biometrics_retention_days - id_images_retention_days - documents_retention_days - pii_retention_days - assessment_prompt_instructions - privacy_contact_email - created_at - updated_at - revision properties: workflow_id: type: string pattern: ^idvw_[0-9a-f]{24}$ tenant_id: type: string workspace_id: type: string name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 500 profile_kind: type: string enum: - individual - organization - both description: > Profile-kind scope (KYB; default both). Session create rejects a workflow whose scope does not match the linked profile's kind (400 idv_workflow_profile_kind_mismatch); the dashboard shows a workflow only for the matching profile kind. steps: type: array minItems: 1 maxItems: 10 description: EXACTLY the flow-steps step schema (same validator as sessions). items: $ref: '#/components/schemas/FlowStep' status: $ref: '#/components/schemas/LifecycleStatus' theme_id: description: Theme reference or null (= use the workspace default theme). oneOf: - type: string pattern: ^idvt_[0-9a-f]{24}$ - type: 'null' is_default: type: boolean retention_days: type: integer minimum: 30 maximum: 365 default: 60 deprecated: true description: > DEPRECATED alias for pii_retention_days, emitted CLAMPED to 30..365 so an editor that predates the four-component split reads a value inside its own bounds rather than normalizing a longer horizon down to its 60-day default and writing that back on save. biometrics_retention_days: type: integer minimum: 30 maximum: 1095 default: 90 description: > 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. Capped at three years by the most permissive biometric regimes; Quebec's one-year ceiling is the tightest. id_images_retention_days: type: integer minimum: 30 maximum: 2555 default: 365 description: > Retention of identity-document captures (id_front / id_back) in days. documents_retention_days: type: integer minimum: 30 maximum: 2555 default: 1825 description: | Retention of consumer-uploaded supporting documents in days. pii_retention_days: type: integer minimum: 30 maximum: 2555 default: 2555 description: > 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. assessment_prompt_instructions: type: string maxLength: 4000 description: > Workflow-admin instructions copied onto future sessions and shown to the review agent as policy guidance. The model treats these as subordinate to system, schema, privacy, and evidence rules. privacy_contact_email: oneOf: - type: string format: email maxLength: 254 - type: string maxLength: 0 description: > Consumer-facing privacy/deletion contact embedded in the consent notice and copied onto future sessions. Required before a workflow can be activated or created as active. profile_update_enabled: type: boolean description: >- Automatic profile-write opt-in (default false). Copied onto sessions at create. flag_settings: $ref: '#/components/schemas/FlagSettings' created_at: type: string format: date-time updated_at: type: string format: date-time revision: type: integer minimum: 1 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: idv_session_not_found message: type: string FlowStep: type: object required: - step_id - type properties: step_id: type: string pattern: ^[a-z0-9_-]{1,64}$ description: Unique per session. type: $ref: '#/components/schemas/StepType' required: type: boolean default: true description: false => the consumer may skip the step. title: type: string minLength: 1 maxLength: 200 description: Optional display override. config: $ref: '#/components/schemas/StepConfig' LifecycleStatus: type: string description: > Shared management lifecycle (workflows AND themes): draft -> active -> archived, archived -> active (restore), draft -> archived. Transitions only via the idempotent POST /activate and /archive endpoints, never via PUT. enum: - draft - active - archived FlagSettings: type: object description: > 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. additionalProperties: type: object properties: raise_for_review: type: boolean StepType: type: string enum: - liveness - id_capture - questionnaire - document_upload StepConfig: type: object description: >- Type-specific step config. Only the fields for the step type are allowed. properties: accepted_id_types: type: array maxItems: 20 description: > id_capture only. Empty/omitted = any supported built-in type plus any custom_id_types configured on the same step. items: $ref: '#/components/schemas/DeclarableIdType' custom_id_types: type: array maxItems: 20 description: > id_capture only. Workflow-local document categories that can be referenced from accepted_id_types and declared by the applicant. items: $ref: '#/components/schemas/CustomIdType' sides: $ref: '#/components/schemas/IdCaptureSides' questions: type: array minItems: 1 maxItems: 50 description: questionnaire only. items: $ref: '#/components/schemas/Question' documents: type: array minItems: 1 maxItems: 5 description: >- document_upload only; the full workflow supports at most five documents. items: $ref: '#/components/schemas/DocumentSpec' DeclarableIdType: description: > Id types a consumer can declare or configure in accepted_id_types. Built-ins are listed explicitly; workflow-local custom ids must be defined in the id_capture step's custom_id_types. `unknown` is an inference outcome, not declarable. `passport` is the one-sided built-in type - declaring it drops id_back when sides=auto. anyOf: - type: string enum: - driver_license - government_id - health_card - passport - national_id - permanent_resident_card - residence_permit - other - type: string pattern: ^[a-z0-9_-]{1,64}$ not: enum: - driver_license - government_id - health_card - passport - national_id - permanent_resident_card - residence_permit - other - unknown CustomIdType: type: object required: - id_type - label - sides properties: id_type: type: string pattern: ^[a-z0-9_-]{1,64}$ description: > Workflow-local id type identifier. Must not match a built-in ID type or `unknown`; accepted_id_types can reference it only within the same id_capture step. label: type: string minLength: 1 maxLength: 120 description: >- Human-readable document type label shown to applicants and reviewers. description: type: string maxLength: 1000 description: > Optional workflow-admin guidance describing the ID, authenticity requirements, and specific details reviewers or the assessment agent should inspect for this custom type. sides: type: string enum: - one_sided - two_sided description: Capture side requirement when the custom type is declared. IdCaptureSides: type: string description: >- auto adapts to the declared document type; one_sided never demands id_back. enum: - auto - two_sided - one_sided default: auto Question: type: object required: - question_id - label - type properties: question_id: type: string pattern: ^[a-z0-9_-]{1,64}$ description: Unique within the step. label: type: string minLength: 1 maxLength: 500 type: $ref: '#/components/schemas/QuestionType' required: type: boolean default: true required_when: allOf: - $ref: '#/components/schemas/QuestionRequiredWhen' description: >- Mutually exclusive with required=true; required defaults to false when this field is present. visible_when: allOf: - $ref: '#/components/schemas/QuestionCondition' description: > Shows this otherwise-optional question only when the earlier, always-shown and required boolean question has the specified value. Mutually exclusive with required=true. If required_when is also present, both fields must contain the same condition. options: type: array maxItems: 50 description: Required for select/multi_select; forbidden otherwise. items: $ref: '#/components/schemas/QuestionOption' DocumentSpec: type: object required: - document_id - label properties: document_id: type: string pattern: ^[a-z0-9_-]{1,64}$ description: Unique within the full workflow. label: type: string minLength: 1 maxLength: 200 description: type: string maxLength: 1000 accepted_content_types: type: array minItems: 1 maxItems: 4 uniqueItems: true description: Defaults to [application/pdf, image/jpeg, image/png] when omitted. items: type: string enum: - application/pdf - image/jpeg - image/png - image/webp required: type: boolean default: true QuestionType: type: string enum: - text - textarea - select - multi_select - date - country - boolean QuestionRequiredWhen: type: object required: - question_id - equals description: > Makes an otherwise-optional question required when an earlier, always-shown and unconditionally required boolean question has the specified value. properties: question_id: type: string pattern: ^[a-z0-9_-]{1,64}$ equals: type: boolean QuestionCondition: allOf: - $ref: '#/components/schemas/QuestionRequiredWhen' description: > Matches an earlier, always-shown and unconditionally required boolean question against the specified value. QuestionOption: type: object required: - value - label properties: value: type: string minLength: 1 maxLength: 128 label: type: string minLength: 1 maxLength: 200 responses: Unauthorized: description: >- Missing or invalid credentials (uniform for token plane, no existence oracle) content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Resolved dashboard user lacks the required capability or scope content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Session/workflow not found or out of scope (indistinguishable by design) content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Domain-state conflict (e.g. concurrent update, illegal transition) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: applicationApiKey: type: apiKey in: header name: Authorization description: >- `Authorization: Api-Key ` (legacy `X-Api-Key` also accepted). dashboardUserToken: type: apiKey in: header name: x-user-token description: > Dashboard session token for Minerva dashboard users. Management routes accept it alongside an application API key; any in-scope workspace user (member or above) can read sessions and record review decisions, while workflow and theme writes need a management-capable role. Send it with the `x-tenant-id` and `x-workspace-id` headers; a header/access mismatch is refused with 403, and when dashboard authentication is disabled (the default) any request carrying this header gets a uniform 401. ````