Step Types - KYC API Documentation

Workflow steps define the sequence of actions users must complete during the KYC onboarding process. Each step type has specific configuration options.

Step Types Overview

Type	Description	Use Case
`document_upload`	Upload and extract data from documents	ID, passport, proof of address
`form_fill`	Custom form fields for data collection	Personal info, company details
`selfie`	Capture selfie photo for face matching	Identity verification
`liveness`	AWS Rekognition Face Liveness detection	Anti-fraud, spoof prevention
`subsession_collection`	Collect verification from related parties	UBOs, submerchants, directors

Common Step Properties

All step types share these base properties:

Property	Type	Required	Description
`step_id`	string	✓	Unique identifier for the step
`order`	integer	✓	Step order (1-based, sequential)
`name`	string	✓	Step display name
`type`	string	✓	Step type: `document_upload`, `form_fill`, `selfie`, `liveness`, or `subsession_collection`
`required`	boolean		Whether this step is required or optional (default: true)
`description`	string		Step description for internal use
`instructions`	string		Instructions shown to the end user

Document Upload Step

Collect and process documents with automatic data extraction.

Configuration

{
  "step_id": "step_1",
  "order": 1,
  "name": "Identity Document",
  "type": "document_upload",
  "instructions": "Please upload a clear photo of your government-issued ID",
  "document_requirements": [
    {
      "document_type": "id",
      "display_name": "Government ID",
      "required": true,
      "require_back": false,
      "allow_multiple_persons": false,
      "auto_extract": true,
      "allow_multiple": false,
      "enable_auto_classification": false,
      "extraction_profile": null,
      "post_upload_validations": []
    }
  ]
}

Document Requirement Properties

Property	Type	Required	Description
`document_type`	string	✓	Type of document to collect
`display_name`	string		Name shown to the user
`required`	boolean		Whether document is required (default: true)
`require_back`	boolean		Require both front and back captures for this document type (default: false)
`allow_multiple_persons`	boolean		Allow collecting the same document type for multiple people (default: false)
`min_persons`	integer		Minimum number of people/documents required when `allow_multiple_persons` is true
`max_persons`	integer		Maximum number of people/documents allowed when `allow_multiple_persons` is true
`person_role_label`	string		Label shown for each person’s role when multiple people are collected
`auto_extract`	boolean		Automatically extract data from document (default: false)
`allow_multiple`	boolean		Allow multiple files for this document type (default: false)
`enable_auto_classification`	boolean		Use AI to auto-classify document type (default: false)
`extraction_profile`	string		Custom extraction profile ID (optional)
`post_upload_validations`	array		Validations to run after upload
`entity_role`	string		Entity role for watchlist tagging: `individual`, `ubo`, `director`, `shareholder`, `representative`. Entities extracted from these documents inherit this tag.

Use entity_role on document requirements when uploading multiple IDs for UBOs or directors. For example:

{
  "document_type": "id",
  "display_name": "UBO ID Documents",
  "auto_extract": true,
  "allow_multiple": true,
  "entity_role": "ubo"
}

All names extracted from these documents will be tagged as ubo when auto-added to watchlists.

Document Types

Individual Documents

Type	Description
`id`	Government-issued ID (passport, driver’s license, national ID)
`id_document`	Alias for `id`
`id_front`	Front side of a government-issued ID
`id_back`	Back side of a government-issued ID
`passport`	Passport specifically
`proof_of_address`	Utility bill, bank statement, etc.
`selfie`	Selfie photo (when uploaded as document)

Company Documents

Type	Description
`company_charter`	Company charter or constitution
`articles_of_incorporation`	Incorporation documents
`tax_certificate`	Tax registration certificate
`shareholder_registry`	Shareholder registry document
`beneficial_owners`	Beneficial ownership declaration
`operating_agreement`	Operating agreement for LLCs

Tax certificate cardinality. A tax_certificate requirement allows one active upload by default because allow_multiple defaults to false; uploading it again replaces the previous document entry for that requirement. Set allow_multiple: true when the workflow must retain several tax certificates in the same step. A session can also contain more than one tax certificate when different steps request the same type. Consequently, consumers of GET /kyc/sessions/{session_id} should treat matching documents and extraction results as a collection keyed by doc_id, not as a session-wide singleton.

Business Documents

Type	Description
`business_license`	Business operating license
`bank_account`	Bank account verification
`bank_ownership`	Bank account ownership verification
`bank_letter`	Bank reference letter

Generic

Type	Description
`custom`	Custom document type
`other`	Other document types

Example: Multiple Document Requirements

{
  "step_id": "documents",
  "order": 1,
  "name": "Upload Documents",
  "type": "document_upload",
  "document_requirements": [
    {
      "document_type": "id",
      "display_name": "Passport or ID Card",
      "required": true,
      "auto_extract": true
    },
    {
      "document_type": "proof_of_address",
      "display_name": "Proof of Address (utility bill, bank statement)",
      "required": true,
      "auto_extract": true,
      "allow_multiple": true
    }
  ]
}

Form Fill Step

Collect structured data using custom form fields with semantic validation.

Configuration

{
  "step_id": "step_2",
  "order": 2,
  "name": "Personal Information",
  "type": "form_fill",
  "instructions": "Please provide your personal details",
  "custom_fields": [
    {
      "field_id": "full_name",
      "name": "Full Name",
      "type": "name",
      "name_type": "individual",
      "validate_lists": true,
      "required": true
    },
    {
      "field_id": "nationality",
      "name": "Nationality",
      "type": "country",
      "country_type": "nationality",
      "required": true
    }
  ]
}

Form Fill Properties

Property	Type	Required	Description
`custom_fields`	array	✓	Array of field definitions. See Field Types for all available fields.

See the Field Types documentation for complete field type reference including semantic fields like country, name, wallet, domain, and volume.

Selfie Step

Capture a selfie photo for face matching against ID documents.

Configuration

{
  "step_id": "step_3",
  "order": 3,
  "name": "Take a Selfie",
  "type": "selfie",
  "instructions": "Please take a clear selfie matching your ID photo. Ensure good lighting and remove glasses.",
  "selfie_config": {
    "require_good_lighting": true,
    "require_face_centered": true
  }
}

Selfie Config Properties

Property	Type	Description
`require_good_lighting`	boolean	Require adequate lighting conditions
`require_face_centered`	boolean	Require face to be centered in frame

For production use with higher security requirements, consider using the liveness step type instead of selfie to prevent spoofing attacks.

Liveness Step

Perform AWS Rekognition Face Liveness detection to verify the user is a real person and prevent spoofing attacks (printed photos, masks, deep fakes).

Configuration

{
  "step_id": "step_3",
  "order": 3,
  "name": "Liveness Verification",
  "type": "liveness",
  "instructions": "Follow the on-screen instructions to verify your identity",
  "liveness_config": {
    "min_confidence": 90.0,
    "challenge_type": "FaceMovementChallenge",
    "save_reference_image": true,
    "save_audit_images": false,
    "use_for_face_match": true,
    "max_retries": 3
  }
}

Liveness Config Properties

Property	Type	Description
`min_confidence`	number	Minimum confidence threshold (0-100) to pass liveness check. Default: 90.0
`challenge_type`	string	Type of liveness challenge: `FaceMovementChallenge` (simpler) or `FaceMovementAndLightChallenge` (more secure). Default: `FaceMovementChallenge`
`save_reference_image`	boolean	Save high-quality reference image from liveness check to S3. Default: true
`save_audit_images`	boolean	Save audit images (up to 4 frames from the video) to S3. Default: false
`use_for_face_match`	boolean	Use the liveness reference image as source for face matching against ID. Default: true
`max_retries`	integer	Maximum number of retry attempts allowed (1-10). Default: 3

Challenge Types

Challenge	Description	Security Level
`FaceMovementChallenge`	User follows head movement prompts	Standard
`FaceMovementAndLightChallenge`	Adds colored light reflections on face	High

Frontend Integration

The frontend must integrate with AWS Rekognition Face Liveness SDK:

// 1. Start liveness session via API
const response = await fetch(`/public/sessions/${accessToken}/liveness/start`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ step_id: "liveness" })
});
const startPayload = await response.json();
const livenessSessionId = startPayload.data.liveness_session_id;
const region = "us-east-1"; // Match the region configured for your tenant

// 2. Use AWS Amplify FaceLivenessDetector component
import { FaceLivenessDetector } from '@aws-amplify/ui-react-liveness';

<FaceLivenessDetector
  sessionId={livenessSessionId}
  region={region}
  onAnalysisComplete={async () => {
    // 3. Complete liveness result via API
    const result = await fetch(`/public/sessions/${accessToken}/liveness/complete`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ liveness_session_id: livenessSessionId })
    });
    const completePayload = await result.json();
    const { passed, confidence } = completePayload.data;
  }}
  onError={(error) => console.error(error)}
/>

Example: Complete Liveness Workflow

{
  "name": "Secure KYC with Liveness",
  "steps": [
    {
      "step_id": "id_upload",
      "order": 1,
      "name": "Upload ID",
      "type": "document_upload",
      "document_requirements": [
        {"document_type": "id", "required": true, "auto_extract": true}
      ]
    },
    {
      "step_id": "liveness",
      "order": 2,
      "name": "Verify Identity",
      "type": "liveness",
      "liveness_config": {
        "min_confidence": 92.0,
        "challenge_type": "FaceMovementAndLightChallenge",
        "use_for_face_match": true
      }
    }
  ],
  "validation_config": {
    "auto_face_match": true,
    "face_match_threshold": 0.85
  }
}

Subsession Collection Step

Collect verification from related parties (UBOs, submerchants, directors) by creating independent subsessions that can be completed by third parties.

Configuration

{
  "step_id": "step_ubos",
  "order": 4,
  "name": "UBO Verification",
  "type": "subsession_collection",
  "instructions": "Add all beneficial owners with 25% or more ownership. Each UBO will receive a separate verification link.",
  "subsession_config": {
    "workflow_id": "ubo-verification-workflow",
    "max_subsessions": 5,
    "min_subsessions": 1,
    "require_completion_before_proceed": true,
    "impact_parent_status": true,
    "ttl_days": 7,
    "category": "ubo",
    "role_label": "Role",
    "role_selection_required": true,
    "allow_multiple_roles": false,
    "role_options": [
      {"value": "ubo", "label": "Ultimate Beneficial Owner"},
      {"value": "director", "label": "Director"}
    ],
    "subsession_label": "UBO",
    "subsession_label_plural": "UBOs",
    "allow_link_regeneration": true
  }
}

Subsession Config Properties

Property	Type	Required	Description
`workflow_id`	string	✓	ID of the workflow to use for subsessions
`max_subsessions`	integer		Maximum number of subsessions allowed (default: 1)
`min_subsessions`	integer		Minimum number of subsessions required to proceed (default: 1)
`require_completion_before_proceed`	boolean		If true, parent session cannot proceed until all subsessions are completed/approved (default: false)
`impact_parent_status`	boolean		If true, subsession status can affect parent session status (default: false)
`ttl_days`	integer		TTL for subsessions in days (overrides default workflow TTL)
`category`	string		Category/tag applied to subsessions created from this step
`role_label`	string		Label shown above role selection
`role_selection_required`	boolean		Whether the user must select at least one role when creating a subsession
`allow_multiple_roles`	boolean		Whether one subsession can have multiple selected roles
`role_options`	array		Allowed role options, each with `value` and `label`
`subsession_label`	string		Singular label for this subsession type
`subsession_label_plural`	string		Plural label for this subsession type
`allow_link_regeneration`	boolean		Whether public users can regenerate subsession links

How It Works

User reaches subsession step: The frontend displays the subsession collection UI
Create subsessions: User creates one or more subsessions (up to max_subsessions)
Share links: Each subsession has its own public access link to share with third parties
Third parties complete verification: Each third party completes their subsession independently
Proceed or wait: Depending on require_completion_before_proceed, the user can proceed immediately or must wait

Completion Behavior

When `require_completion_before_proceed: false`

User can complete the step and proceed immediately after creating subsessions
Subsessions continue independently
Parent session can be approved even if subsessions are pending

When `require_completion_before_proceed: true`

User cannot proceed until all created subsessions are completed or approved
Frontend should show subsession status and block the “Continue” button
Useful for strict UBO verification requirements

Status Impact

When impact_parent_status: true:

If any subsession is rejected, the parent session may be flagged for manual review
All subsession results are aggregated in the parent session’s processing results
Watchlist hits or adverse media from subsessions are included in parent session

Example: UBO Workflow for Subsessions

Create a simple workflow for UBO verification:

{
  "name": "UBO Verification",
  "description": "Short verification for beneficial owners",
  "entity_types": ["individual"],
  "steps": [
    {
      "step_id": "id_upload",
      "order": 1,
      "name": "ID Document",
      "type": "document_upload",
      "instructions": "Upload your passport or national ID",
      "document_requirements": [
        {
          "document_type": "id",
          "required": true,
          "auto_extract": true,
          "entity_role": "ubo"
        }
      ]
    },
    {
      "step_id": "liveness",
      "order": 2,
      "name": "Identity Verification",
      "type": "liveness",
      "liveness_config": {
        "min_confidence": 90.0,
        "challenge_type": "FaceMovementChallenge",
        "use_for_face_match": true
      }
    }
  ],
  "validation_config": {
    "run_lists": true,
    "auto_face_match": true
  }
}

Example: Company KYC with UBO Subsessions

{
  "name": "Company KYC with UBOs",
  "description": "Full company onboarding with UBO verification",
  "entity_types": ["company"],
  "steps": [
    {
      "step_id": "company_docs",
      "order": 1,
      "name": "Company Documents",
      "type": "document_upload",
      "document_requirements": [
        {"document_type": "articles_of_incorporation", "required": true},
        {"document_type": "beneficial_owners", "required": true}
      ]
    },
    {
      "step_id": "company_info",
      "order": 2,
      "name": "Company Information",
      "type": "form_fill",
      "custom_fields": [
        {"field_id": "company_name", "name": "Company Name", "type": "name", "name_type": "company", "required": true},
        {"field_id": "incorporation_country", "name": "Country of Incorporation", "type": "country", "required": true},
        {"field_id": "registration_number", "name": "Registration Number", "type": "text", "required": true}
      ]
    },
    {
      "step_id": "representative",
      "order": 3,
      "name": "Representative Verification",
      "type": "liveness",
      "instructions": "Complete liveness verification as company representative",
      "liveness_config": {
        "min_confidence": 90.0,
        "use_for_face_match": true
      }
    },
    {
      "step_id": "ubos",
      "order": 4,
      "name": "Beneficial Owner Verification",
      "type": "subsession_collection",
      "instructions": "Add all beneficial owners with 25% or more ownership. Each will receive a verification link.",
      "subsession_config": {
        "workflow_id": "ubo-verification-workflow",
        "max_subsessions": 10,
        "require_completion_before_proceed": true,
        "impact_parent_status": true,
        "ttl_days": 14
      }
    }
  ],
  "validation_config": {
    "run_lists": true,
    "run_adverse_media": true
  }
}

Frontend Integration

The frontend receives the subsession_collection step configuration and should:

Display the step instructions
Show a form/button to create new subsessions
List existing subsessions with their status
Show copy/share buttons for subsession links
Allow regenerating links if needed
Block progression if require_completion_before_proceed is true and subsessions are pending

See Public Sessions API - Subsessions for the API endpoints used by the frontend.

Complete Workflow Example

{
  "name": "Complete Individual KYC",
  "description": "Full KYC with ID, liveness, and form data",
  "entity_types": ["individual"],
  "steps": [
    {
      "step_id": "documents",
      "order": 1,
      "name": "Identity Documents",
      "type": "document_upload",
      "instructions": "Please upload your passport or government ID",
      "document_requirements": [
        {
          "document_type": "id",
          "display_name": "Passport or ID Card",
          "required": true,
          "auto_extract": true
        },
        {
          "document_type": "proof_of_address",
          "display_name": "Proof of Address",
          "required": false,
          "auto_extract": true
        }
      ]
    },
    {
      "step_id": "liveness",
      "order": 2,
      "name": "Identity Verification",
      "type": "liveness",
      "instructions": "Complete the liveness check to verify your identity",
      "liveness_config": {
        "min_confidence": 90.0,
        "challenge_type": "FaceMovementChallenge",
        "save_reference_image": true,
        "use_for_face_match": true,
        "max_retries": 3
      }
    },
    {
      "step_id": "personal_info",
      "order": 3,
      "name": "Personal Information",
      "type": "form_fill",
      "instructions": "Please verify and complete your information",
      "custom_fields": [
        {
          "field_id": "full_name",
          "name": "Full Legal Name",
          "type": "name",
          "name_type": "individual",
          "validate_lists": true,
          "validate_adverse_media": false,
          "required": true
        },
        {
          "field_id": "date_of_birth",
          "name": "Date of Birth",
          "type": "date",
          "required": true
        },
        {
          "field_id": "nationality",
          "name": "Nationality",
          "type": "country",
          "country_type": "nationality",
          "required": true
        },
        {
          "field_id": "residence",
          "name": "Country of Residence",
          "type": "country",
          "country_type": "residence",
          "required": true
        },
        {
          "field_id": "email",
          "name": "Email Address",
          "type": "email",
          "validate_email": true,
          "block_disposable": true,
          "required": true
        },
        {
          "field_id": "phone",
          "name": "Phone Number",
          "type": "phone",
          "format": "international",
          "require_mobile": true,
          "required": true
        },
        {
          "field_id": "pep_status",
          "name": "Are you a Politically Exposed Person (PEP)?",
          "type": "select",
          "options": ["No", "Yes - Current PEP", "Yes - Former PEP", "Yes - Family member of PEP"],
          "required": true
        }
      ]
    }
  ],
  "validation_config": {
    "run_lists": true,
    "run_adverse_media": true,
    "auto_face_match": true,
    "face_match_threshold": 0.85,
    "automation_rules": {
      "enabled": true,
      "auto_process": true,
      "country_rules": [
        {"country_code": "KP", "action": "auto_deny", "applies_to": ["all"]},
        {"country_code": "IR", "action": "manual_review", "applies_to": ["nationality", "residence"]}
      ],
      "form_field_rules": [
        {
          "field_id": "pep_status",
          "operator": "not_equals",
          "value": "No",
          "action": "manual_review",
          "reason": "User declared PEP status"
        }
      ],
      "default_action": "manual_review"
    }
  }
}

Field Types - All available field types
Automation Rules - Automation configuration
Sessions - Managing KYC sessions
Public Sessions - Subsessions - Public API for subsession management

​Step Types Overview

​Common Step Properties

​Document Upload Step

​Configuration

​Document Requirement Properties

​Document Types

​Individual Documents

​Company Documents

​Business Documents

​Generic

​Example: Multiple Document Requirements

​Form Fill Step

​Configuration

​Form Fill Properties

​Selfie Step

​Configuration

​Selfie Config Properties

​Liveness Step

​Configuration

​Liveness Config Properties

​Challenge Types

​Frontend Integration

​Example: Complete Liveness Workflow

​Subsession Collection Step

​Configuration

​Subsession Config Properties

​How It Works

​Completion Behavior

​When require_completion_before_proceed: false

​When require_completion_before_proceed: true

​Status Impact

​Example: UBO Workflow for Subsessions

​Example: Company KYC with UBO Subsessions

​Frontend Integration

​Complete Workflow Example

​Related Documentation

Step Types Overview

Common Step Properties

Document Upload Step

Configuration

Document Requirement Properties

Document Types

Individual Documents

Company Documents

Business Documents

Generic

Example: Multiple Document Requirements

Form Fill Step

Configuration

Form Fill Properties

Selfie Step

Configuration

Selfie Config Properties

Liveness Step

Configuration

Liveness Config Properties

Challenge Types

Frontend Integration

Example: Complete Liveness Workflow

Subsession Collection Step

Configuration

Subsession Config Properties

How It Works

Completion Behavior

When `require_completion_before_proceed: false`

When `require_completion_before_proceed: true`

Status Impact

Example: UBO Workflow for Subsessions

Example: Company KYC with UBO Subsessions

Frontend Integration

Complete Workflow Example

Related Documentation