> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

Manage KYC onboarding workflows that define the steps and validation requirements for end-user onboarding processes. Workflows allow you to create customizable onboarding experiences with document upload, form fields, selfie verification, liveness detection, remediation behavior, and automated validation checks with **automation rules**.

## Overview

Workflows define the structure and steps for KYC onboarding sessions. Each workflow consists of:

* **Steps**: Sequential steps users must complete (document upload, form fields, selfie, liveness, etc.)
* **Validation Configuration**: Automated checks to run (watchlists, crypto, adverse media, face match)
* **Automation Rules**: Advanced rules for automatic decisions (approve/deny/flag/manual review)
* **Entity Types**: Target entity types (individual, company, or both)
* **Versioning**: Workflow updates create new versions while active sessions use their original version

<CardGroup cols={2}>
  <Card title="Step Types" icon="list-check" href="/api-reference/workflows/steps">
    Document upload, form fields, selfie, liveness detection, and validation steps
  </Card>

  <Card title="Field Types" icon="input-text" href="/api-reference/workflows/fields">
    Text, number, date, country, name, wallet, email, phone, and semantic field types
  </Card>

  <Card title="Automation Rules" icon="robot" href="/api-reference/workflows/automations">
    Country rules, list matches, face dedup, document validation, and more
  </Card>

  <Card title="Examples" icon="code" href="/api-reference/workflows/examples">
    Complete integration examples and common workflow patterns
  </Card>
</CardGroup>

## Endpoints

| Method   | Endpoint                                | Description                           |
| -------- | --------------------------------------- | ------------------------------------- |
| `POST`   | `/kyc/workflows`                        | Create a new workflow                 |
| `POST`   | `/kyc/workflows/from-template/{type}`   | Create workflow from template         |
| `GET`    | `/kyc/workflows`                        | List all workflows                    |
| `GET`    | `/kyc/workflows/{workflow_id}`          | Get workflow details                  |
| `GET`    | `/kyc/workflows/{workflow_id}/versions` | List workflow versions                |
| `PUT`    | `/kyc/workflows/{workflow_id}`          | Update workflow (creates new version) |
| `DELETE` | `/kyc/workflows/{workflow_id}`          | Soft delete workflow                  |

## Authentication

Requires `kyc:create` permission for creating workflows and `kyc:read` permission for retrieving workflows. Include your Bearer token in the Authorization header.

## Available Templates

Pre-built templates for common use cases:

| Template              | Description                                                  | Entity Type |
| --------------------- | ------------------------------------------------------------ | ----------- |
| `basic-kyc`           | Standard individual KYC with ID, address, and personal info  | Individual  |
| `company-kyc`         | Company KYC with incorporation docs, shareholders, directors | Company     |
| `merchant-onboarding` | Merchant onboarding with business license and sub-merchants  | Both        |
| `pep-enhanced`        | Enhanced due diligence for high-risk/PEP individuals         | Individual  |

## Create Workflow

Create a new custom workflow.

### Endpoint

```
POST /kyc/workflows
```

### Request Body Parameters

| Property            | Type   | Required | Description                                                                                                                                  |
| ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string | ✓        | Workflow name                                                                                                                                |
| `description`       | string |          | Workflow description                                                                                                                         |
| `template_type`     | string |          | Template: `basic-kyc`, `company-kyc`, `merchant-onboarding`, `pep-enhanced`, or `custom` (default)                                           |
| `entity_types`      | array  |          | Target entity types: `individual`, `company`, or both                                                                                        |
| `industry`          | string |          | Target industry (e.g., "Financial Services", "E-commerce")                                                                                   |
| `tags`              | array  |          | Tags for categorization                                                                                                                      |
| `custom_tags`       | object |          | Key-value string pairs (`{"key": "value"}`) included in all session webhook payloads. Max 20 entries, 50 chars per key, 200 chars per value. |
| `steps`             | array  | ✓        | Array of workflow step objects. See [Step Types](/api-reference/workflows/steps).                                                            |
| `validation_config` | object |          | Validation configuration (see below)                                                                                                         |

#### validation\_config Properties

| Property                   | Type    | Description                                                                              |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `run_lists`                | boolean | Run watchlist checks (OFAC, UN, etc.). Default: true                                     |
| `run_crypto`               | boolean | Run crypto wallet checks. Default: false                                                 |
| `run_adverse_media`        | boolean | Run adverse media checks. Default: false                                                 |
| `auto_face_match`          | boolean | Automatically run face matching between ID and selfie. Default: false                    |
| `face_match_threshold`     | number  | Minimum confidence threshold for face match (0.0-1.0). Default: 0.8                      |
| `cross_validate_documents` | boolean | Validate consistency between uploaded documents. Default: true                           |
| `correction_resolution`    | object  | Controls what happens after the customer resolves reviewer-requested corrections         |
| `automation_rules`         | object  | Advanced automation rules. See [Automation Rules](/api-reference/workflows/automations). |

#### correction\_resolution Properties

| Property              | Type   | Description                                                                                                                                                                     |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`                | string | What happens after all corrections are resolved: `manual_review` (default), `auto_process`, or `completed`                                                                      |
| `post_reprocess_mode` | string | What happens when a reviewer manually reprocesses a remediated session: `manual_review` keeps the session awaiting reviewer decision; `autoprocess` applies automation outcomes |

## Request Examples

### Create Basic KYC Workflow

```bash theme={null}
curl -X POST https://kyc.legaltalent.ai/kyc/workflows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic KYC",
    "description": "Standard KYC onboarding workflow",
    "entity_types": ["individual"],
    "custom_tags": {
      "department": "onboarding",
      "region": "latam"
    },
    "steps": [
      {
        "step_id": "step_1",
        "order": 1,
        "name": "ID Document",
        "type": "document_upload",
        "document_requirements": [
          {
            "document_type": "id",
            "required": true,
            "auto_extract": true
          }
        ]
      },
      {
        "step_id": "step_2",
        "order": 2,
        "name": "Selfie",
        "type": "selfie",
        "instructions": "Please take a clear selfie matching your ID photo"
      },
      {
        "step_id": "step_3",
        "order": 3,
        "name": "Personal Information",
        "type": "form_fill",
        "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
          },
          {
            "field_id": "email",
            "name": "Email",
            "type": "email",
            "validate_email": true,
            "required": true
          }
        ]
      }
    ],
    "validation_config": {
      "run_lists": true,
      "run_crypto": false,
      "run_adverse_media": false,
      "auto_face_match": true,
      "face_match_threshold": 0.8,
      "automation_rules": {
        "enabled": true,
        "auto_process": true,
        "country_rules": [
          {
            "country_code": "KP",
            "action": "auto_deny",
            "applies_to": ["all"],
            "reason": "Sanctioned country"
          }
        ],
        "face_match_threshold": 0.85,
        "face_match_action_on_fail": "auto_deny",
        "default_action": "manual_review"
      }
    }
  }'
```

### Create from Template

```bash theme={null}
curl -X POST https://kyc.legaltalent.ai/kyc/workflows/from-template/basic-kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Basic KYC Workflow",
    "description": "Customized basic KYC for my application"
  }'
```

### Create Workflow with Liveness Detection

```bash theme={null}
curl -X POST https://kyc.legaltalent.ai/kyc/workflows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "KYC with Liveness",
    "entity_types": ["individual"],
    "steps": [
      {
        "step_id": "step_1",
        "order": 1,
        "name": "ID Document",
        "type": "document_upload",
        "document_requirements": [
          {"document_type": "id", "required": true, "auto_extract": true}
        ]
      },
      {
        "step_id": "step_2",
        "order": 2,
        "name": "Liveness Check",
        "type": "liveness",
        "liveness_config": {
          "min_confidence": 90.0,
          "challenge_type": "FaceMovementChallenge",
          "save_reference_image": true,
          "use_for_face_match": true,
          "max_retries": 3
        }
      }
    ],
    "validation_config": {
      "run_lists": true,
      "auto_face_match": true
    }
  }'
```

## Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "Basic KYC",
    "description": "Standard KYC onboarding workflow",
    "template_type": "custom",
    "entity_types": ["individual"],
    "custom_tags": {
      "department": "onboarding",
      "region": "latam"
    },
    "steps": [...],
    "validation_config": {
      "run_lists": true,
      "run_crypto": false,
      "run_adverse_media": false,
      "auto_face_match": true,
      "face_match_threshold": 0.8,
      "cross_validate_documents": true,
      "automation_rules": {
        "enabled": true,
        "auto_process": true,
        "country_rules": [...],
        "default_action": "manual_review"
      }
    },
    "version": 1,
    "is_active": true,
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}
```

## List Workflows

Retrieve all workflows for your tenant.

### Endpoint

```
GET /kyc/workflows
```

### Request Example

```bash theme={null}
curl https://kyc.legaltalent.ai/kyc/workflows \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "workflows": [
      {
        "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Basic KYC",
        "description": "Standard KYC onboarding workflow",
        "template_type": "basic-kyc",
        "step_count": 3,
        "is_active": true,
        "version": 1,
        "created_at": "2024-11-22T10:30:00Z",
        "updated_at": "2024-11-22T10:30:00Z"
      }
    ]
  }
}
```

## Get Workflow Details

Retrieve detailed information about a specific workflow.

### Endpoint

```
GET /kyc/workflows/{workflow_id}
```

### Query Parameters

| Parameter | Type    | Description                                       |
| --------- | ------- | ------------------------------------------------- |
| `version` | integer | Specific version to retrieve (defaults to latest) |

### Request Example

```bash theme={null}
curl https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Update Workflow

Update a workflow (creates a new version).

### Endpoint

```
PUT /kyc/workflows/{workflow_id}
```

### Request Body

Same as create workflow, but all fields are optional (only include fields you want to update).

### Request Example

```bash theme={null}
curl -X PUT https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow Name",
    "validation_config": {
      "run_lists": true,
      "run_crypto": true,
      "run_adverse_media": true,
      "auto_face_match": true,
      "automation_rules": {
        "enabled": true,
        "auto_process": true
      }
    }
  }'
```

## Delete Workflow

Soft delete a workflow.

### Endpoint

```
DELETE /kyc/workflows/{workflow_id}
```

### Request Example

```bash theme={null}
curl -X DELETE https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true
  }
}
```

## List Workflow Versions

Retrieve all versions of a workflow.

### Endpoint

```
GET /kyc/workflows/{workflow_id}/versions
```

### Request Example

```bash theme={null}
curl https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000/versions \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "versions": [
      {
        "version": 2,
        "created_at": "2024-11-23T14:00:00Z",
        "is_active": true
      },
      {
        "version": 1,
        "created_at": "2024-11-22T10:30:00Z",
        "is_active": false
      }
    ]
  }
}
```

## Status Codes

| Code | Description                                |
| ---- | ------------------------------------------ |
| 200  | Success                                    |
| 201  | Created - Workflow created successfully    |
| 400  | Bad Request - Invalid parameters           |
| 401  | Unauthorized - Missing or invalid token    |
| 403  | Forbidden - Insufficient permissions       |
| 404  | Not Found - Workflow or template not found |
| 500  | Internal Server Error                      |

## Best Practices

* **Use Templates**: Start with a template and customize as needed
* **Step Ordering**: Ensure step orders are sequential (1, 2, 3, etc.)
* **Liveness over Selfie**: Use `liveness` step type for better fraud prevention
* **Face Matching**: Enable `auto_face_match` when collecting both ID and selfie/liveness
* **Automation Rules**: Configure automation rules for automatic decision making
* **Semantic Fields**: Use semantic field types (country, name, wallet) for automatic validation
* **Entity Types**: Set appropriate entity types to filter workflows in your UI
* **Versioning**: Track workflow versions - active sessions continue using their original version
* **Custom Tags**: Use `custom_tags` to attach metadata (e.g., department, region, campaign) that will be forwarded in all session webhook payloads

## Related Documentation

* [Step Types](/api-reference/workflows/steps) - Detailed step configuration
* [Field Types](/api-reference/workflows/fields) - All available field types
* [Automation Rules](/api-reference/workflows/automations) - Complete automation reference
* [Examples](/api-reference/workflows/examples) - Integration examples