Workflows - KYC API Documentation

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, and automated validation checks.

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, etc.)
Validation Configuration: Automated checks to run (watchlists, crypto, adverse media, face match)
Entity Types: Target entity types (individual, company, or both)
Versioning: Workflow updates create new versions while active sessions use their original version

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

Step Types

Type	Description
`document_upload`	Upload and extract document data
`form_fill`	Custom form fields for data collection
`selfie`	Capture selfie photo for face matching
`liveness`	Liveness detection check
`validation`	Automated validation checks

Document Requirements

For document_upload steps, specify which documents to collect:

{
  "document_requirements": [
    {
      "document_type": "id",
      "display_name": "Government ID",
      "required": true,
      "auto_extract": true,
      "allow_multiple": false
    }
  ]
}

Document Types

Type	Description
`id`	Government-issued ID (passport, driver’s license, national ID)
`proof_of_address`	Utility bill, bank statement, etc.
`articles_of_incorporation`	Company incorporation documents
`tax_certificate`	Tax registration certificate
`shareholder_registry`	Shareholder registry document
`beneficial_owners`	Beneficial ownership declaration
`business_license`	Business operating license
`bank_ownership`	Bank account ownership verification

Custom Field Types

For form_fill steps, define custom fields:

Type	Description
`text`	Text input
`number`	Number input
`date`	Date picker
`boolean`	Checkbox
`select`	Dropdown selection
`multi_select`	Multi-select dropdown
`file`	File upload
`email`	Email input with validation
`phone`	Phone number input
`url`	URL input with optional validation
`currency`	Currency amount input
`percentage`	Percentage input
`address`	Full address input
`entity_array`	Array of entities (for directors, shareholders)
`sub_merchant`	Sub-merchant information

Request Examples

Create Custom Workflow

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"],
    "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": "text",
            "required": true
          },
          {
            "field_id": "date_of_birth",
            "name": "Date of Birth",
            "type": "date",
            "required": true
          },
          {
            "field_id": "email",
            "name": "Email",
            "type": "email",
            "required": true
          },
          {
            "field_id": "phone",
            "name": "Phone Number",
            "type": "phone",
            "required": false
          }
        ]
      }
    ],
    "validation_config": {
      "run_lists": true,
      "run_crypto": false,
      "run_adverse_media": false,
      "auto_face_match": true,
      "face_match_threshold": 0.8
    }
  }'

Create from Template

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 Company KYC Workflow

curl -X POST https://kyc.legaltalent.ai/kyc/workflows/from-template/company-kyc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Onboarding",
    "description": "Full company KYC with directors and shareholders"
  }'

Create Merchant Onboarding Workflow

curl -X POST https://kyc.legaltalent.ai/kyc/workflows/from-template/merchant-onboarding \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Merchant Onboarding",
    "description": "Merchant verification with sub-merchant details"
  }'

Create PEP Enhanced Workflow

curl -X POST https://kyc.legaltalent.ai/kyc/workflows/from-template/pep-enhanced \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Due Diligence",
    "description": "Enhanced KYC for high-risk individuals"
  }'

Response Format

{
  "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"],
    "steps": [
      {
        "step_id": "step_1",
        "order": 1,
        "name": "ID Document",
        "type": "document_upload",
        "document_requirements": [
          {
            "document_type": "id",
            "required": true,
            "auto_extract": true
          }
        ]
      }
    ],
    "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
    },
    "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

curl https://kyc.legaltalent.ai/kyc/workflows \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "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

Request Example

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

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
    }
  }'

Delete Workflow

Soft delete a workflow.

Endpoint

DELETE /kyc/workflows/{workflow_id}

Request Example

curl -X DELETE https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "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

curl https://kyc.legaltalent.ai/kyc/workflows/550e8400-e29b-41d4-a716-446655440000/versions \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "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.)
Face Matching: Enable auto_face_match when collecting both ID and selfie
Validation Config: Configure validation checks based on your compliance requirements
Entity Types: Set appropriate entity types to filter workflows in your UI
Versioning: Track workflow versions - active sessions continue using their original version

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

​Overview

​Endpoints

​Authentication

​Available Templates

​Create Workflow

​Endpoint

​Request Body Parameters

​Step Types

​Document Requirements

​Document Types

​Custom Field Types

​Request Examples

​Create Custom Workflow

​Create from Template

​Create Company KYC Workflow

​Create Merchant Onboarding Workflow

​Create PEP Enhanced Workflow

​Response Format

​List Workflows

​Endpoint

​Request Example

​Response Format

​Get Workflow Details

​Endpoint

​Query Parameters

​Request Example

​Update Workflow

​Endpoint

​Request Body

​Request Example

​Delete Workflow

​Endpoint

​Request Example

​Response Format

​List Workflow Versions

​Endpoint

​Request Example

​Response Format

​Status Codes

​Best Practices

Overview

Endpoints

Authentication

Available Templates

Create Workflow

Endpoint

Request Body Parameters

Step Types

Document Requirements

Document Types

Custom Field Types

Request Examples

Create Custom Workflow

Create from Template

Create Company KYC Workflow

Create Merchant Onboarding Workflow

Create PEP Enhanced Workflow

Response Format

List Workflows

Endpoint

Request Example

Response Format

Get Workflow Details

Endpoint

Query Parameters

Request Example

Update Workflow

Endpoint

Request Body

Request Example

Delete Workflow

Endpoint

Request Example

Response Format

List Workflow Versions

Endpoint

Request Example

Response Format

Status Codes

Best Practices