Sessions - KYC API Documentation

Manage KYC onboarding sessions for end users. Sessions track progress through workflows, store document uploads, and manage the onboarding process from creation to approval.

Overview

Sessions represent individual KYC onboarding processes for end users. Each session:

Links to a Workflow: Defines the steps and requirements
Tracks Progress: Monitors which steps are completed
Stores Documents: Uploaded documents are stored securely
Runs Validations: Automated checks (watchlists, crypto, adverse media, face match)
Public Access: End users access sessions via public access tokens

Endpoints

Method	Endpoint	Description
`POST`	`/kyc/sessions`	Create a new session
`GET`	`/kyc/sessions`	List sessions (paginated)
`GET`	`/kyc/sessions/{session_id}`	Get session details
`PATCH`	`/kyc/sessions/{session_id}`	Update session status
`DELETE`	`/kyc/sessions/{session_id}`	Delete session
`POST`	`/kyc/sessions/{session_id}/generate-link`	Generate/regenerate access link
`POST`	`/kyc/sessions/{session_id}/validate`	Run validation checks
`POST`	`/kyc/sessions/{session_id}/process`	Process completed session
`GET`	`/kyc/sessions/{session_id}/documents/{doc_id}/url`	Get document download URL
`POST`	`/kyc/sessions/{session_id}/subsessions`	Create a subsession
`GET`	`/kyc/sessions/{session_id}/subsessions`	List subsessions
`POST`	`/kyc/sessions/{session_id}/subsessions/{sub_id}/regenerate-link`	Regenerate subsession link
`DELETE`	`/kyc/sessions/{session_id}/subsessions/{sub_id}`	Delete subsession

Authentication

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

Create Session

Create a new KYC onboarding session for an end user.

Endpoint

POST /kyc/sessions

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "ttl_days": 7,
    "metadata": {
      "user_email": "user@example.com",
      "user_name": "John Doe"
    }
  }'

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_version": 1,
    "status": "active",
    "access_token": "770e8400-e29b-41d4-a716-446655440002",
    "access_link": "https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002",
    "current_step_index": 0,
    "expires_at": 1732278600,
    "ttl_days": 7,
    "steps_data": [
      {
        "step_id": "step_1",
        "status": "pending"
      },
      {
        "step_id": "step_2",
        "status": "pending"
      }
    ],
    "metadata": {
      "user_email": "user@example.com",
      "user_name": "John Doe"
    },
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

List Sessions

Retrieve all sessions for your tenant with pagination, filtering, and optional summary statistics.

Endpoint

GET /kyc/sessions

Query Parameters

Request Example

# Basic listing with status filter
curl "https://kyc.legaltalent.ai/kyc/sessions?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by date range and workflow
curl "https://kyc.legaltalent.ai/kyc/sessions?workflow_id=550e8400-e29b-41d4-a716-446655440000&created_from=2024-01-01T00:00:00Z&created_to=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get sessions with summary statistics
curl "https://kyc.legaltalent.ai/kyc/sessions?include_summary=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter multiple statuses
curl "https://kyc.legaltalent.ai/kyc/sessions?status_list=approved,rejected,manual_review&include_summary=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "sessions": [
      {
        "session_id": "660e8400-e29b-41d4-a716-446655440001",
        "tenant_id": "tenant123",
        "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
        "workflow_name": "Basic KYC",
        "status": "approved",
        "current_step_index": 3,
        "total_steps": 3,
        "progress_percent": 100,
        "expires_at": 1732278600,
        "metadata": {
          "user_email": "user@example.com",
          "user_name": "John Doe"
        },
        "customer_id": "cust_abc123",
        "risk_score": 25.5,
        "risk_level": "low",
        "created_at": "2024-11-22T10:30:00Z",
        "updated_at": "2024-11-22T10:35:00Z"
      }
    ],
    "next_key": "eyJzZXNzaW9uX2lkIjoiNjYwZTg0MDA...",
    "summary": {
      "status_counts": {
        "active": 5,
        "completed": 3,
        "approved": 42,
        "rejected": 8,
        "manual_review": 12,
        "expired": 2
      },
      "total": 72,
      "avg_risk_score": 35.2,
      "sessions_with_risk_score": 50
    }
  }
}

Summary Statistics

When include_summary=true, the response includes aggregate statistics for all sessions matching the filters (not just the current page):

Field	Description
`status_counts`	Count of sessions per status
`total`	Total number of sessions matching filters
`avg_risk_score`	Average risk score across scored sessions
`sessions_with_risk_score`	Number of sessions that have a risk score

The summary requires scanning all matching sessions, which may increase response time for tenants with many sessions. Use filters (workflow_id, date range) to limit the scope when possible.

## Get Session Details

Retrieve detailed information about a specific session.

### Endpoint

GET /kyc/sessions/

### Request Example

```bash
curl https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "tenant_id": "tenant123",
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "workflow_version": 1,
    "status": "completed",
    "access_token": "770e8400-e29b-41d4-a716-446655440002",
    "current_step_index": 3,
    "steps_data": [
      {
        "step_id": "step_1",
        "status": "completed",
        "started_at": "2024-11-22T10:31:00Z",
        "completed_at": "2024-11-22T10:32:00Z",
        "documents": [
          {
            "doc_id": "doc_abc123",
            "type": "id",
            "file_name": "passport.jpg",
            "mime_type": "image/jpeg",
            "uploaded_at": "2024-11-22T10:32:00Z"
          }
        ]
      },
      {
        "step_id": "step_2",
        "status": "completed",
        "started_at": "2024-11-22T10:33:00Z",
        "completed_at": "2024-11-22T10:34:00Z",
        "documents": [
          {
            "doc_id": "doc_def456",
            "type": "selfie",
            "file_name": "selfie.jpg",
            "mime_type": "image/jpeg",
            "uploaded_at": "2024-11-22T10:34:00Z"
          }
        ]
      },
      {
        "step_id": "step_3",
        "status": "completed",
        "started_at": "2024-11-22T10:35:00Z",
        "completed_at": "2024-11-22T10:36:00Z",
        "form_data": {
          "full_name": "John Doe",
          "date_of_birth": "1990-01-15",
          "email": "john@example.com"
        }
      }
    ],
    "form_data": {
      "full_name": {
        "field_id": "field_abc123",
        "name": "Full Name",
        "type": "name",
        "value": "John Doe"
      },
      "date_of_birth": {
        "field_id": "field_xyz789",
        "name": "Date of Birth",
        "type": "date",
        "value": "1990-01-15"
      },
      "email": {
        "field_id": "field_email456",
        "name": "Email",
        "type": "email",
        "value": "john@example.com"
      }
    },
    "metadata": {
      "user_email": "user@example.com",
      "user_name": "John Doe"
    },
    "expires_at": 1732278600,
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:36:00Z",
    "completed_at": "2024-11-22T10:36:00Z"
  }
}

Process Session

Process a completed session - extract document data, run cross-validation, face matching, and external validations. This is the main endpoint to call after a session is completed to get final results.

Endpoint

POST /kyc/sessions/{session_id}/process

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/process \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "processed",
    "processing_results": {
      "extraction_results": {
        "doc_abc123": {
          "full_name": "JOHN DOE",
          "document_number": "AB1234567",
          "date_of_birth": "1990-01-15",
          "nationality": "US",
          "expiry_date": "2030-01-15"
        }
      },
      "cross_validation": {
        "status": "passed",
        "warnings": [],
        "errors": []
      },
      "face_match_result": {
        "status": "matched",
        "confidence": 0.95,
        "threshold": 0.8
      },
      "external_validations": {
        "lists_check": {
          "is_match": false,
          "match_count": 0,
          "lists_checked": ["ofac", "un", "eu"]
        },
        "crypto_check": null,
        "adverse_media_check": {
          "risk_score": 10,
          "decision": "CLEAR"
        }
      },
      "web_validation_results": [],
      "final_decision": "approved",
      "processed_at": "2024-11-22T10:45:00Z",
      "processing_time_ms": 5200
    }
  }
}

Processing Results Fields

Field	Description
`extraction_results`	Extracted data from each uploaded document
`cross_validation`	Consistency check between documents and form data
`face_match_result`	Face comparison between ID and selfie (if configured)
`external_validations`	Results from watchlist, crypto, and adverse media checks
`web_validation_results`	URL validation results (if configured)
`final_decision`	Automatic decision: `approved`, `manual_review`, or `rejected`

Update Session Status

Manually update the status of a session (approve, reject, or request manual review).

Endpoint

PATCH /kyc/sessions/{session_id}

Request Body Parameters

Request Example

curl -X PATCH https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "notes": "All documents verified successfully"
  }'

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "approved",
    "updated_at": "2024-11-22T10:50:00Z"
  }
}

Generate Access Link

Generate or regenerate the public access link for a session. Use this to get a new link if the previous one was compromised or needs to be refreshed.

Endpoint

POST /kyc/sessions/{session_id}/generate-link

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/generate-link \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "access_token": "880e8400-e29b-41d4-a716-446655440003",
    "link": "https://kyc.legaltalent.ai/public/sessions/880e8400-e29b-41d4-a716-446655440003",
    "expires_at": 1732278600
  }
}

Run Validation Checks

Manually trigger validation checks for a session without full processing.

Endpoint

POST /kyc/sessions/{session_id}/validate

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/validate \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "validation_results": {
      "lists_check": {
        "is_match": false,
        "match_count": 0
      },
      "crypto_check": null,
      "adverse_media_check": {
        "risk_score": 15,
        "decision": "CLEAR"
      },
      "validated_at": "2024-11-22T10:45:00Z"
    }
  }
}

Get Document URL

Get a presigned URL to download a document from a session.

Endpoint

GET /kyc/sessions/{session_id}/documents/{doc_id}/url

Request Example

curl https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/documents/doc_abc123/url \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "presigned_url": "https://s3.amazonaws.com/bucket/...",
    "file_name": "passport.jpg",
    "mime_type": "image/jpeg",
    "doc_id": "doc_abc123",
    "document_type": "id",
    "uploaded_at": "2024-11-22T10:32:00Z",
    "expires_at": 1732282200
  }
}

Delete Session

Delete a session and all associated data.

Endpoint

DELETE /kyc/sessions/{session_id}

Request Example

curl -X DELETE https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "deleted": true
  }
}

Session Statuses

Status	Description
`draft`	Session created but not yet started
`active`	Session is in progress
`completed`	All steps completed, ready for processing
`processing`	Session is being processed
`processed`	Processing complete, awaiting review
`expired`	Session expired (TTL exceeded)
`approved`	Session approved
`rejected`	Session rejected
`manual_review`	Session requires manual review

Step Statuses

Status	Description
`pending`	Step not yet started
`in_progress`	Step in progress
`completed`	Step completed
`skipped`	Step was skipped

Status Codes

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

Subsessions

Subsessions allow you to collect verification from related parties (UBOs, submerchants, directors) during the main onboarding process. Each subsession is a complete, independent session linked to a parent session.

Create Subsession

Create a new subsession for verification of a related party.

Endpoint

POST /kyc/sessions/{session_id}/subsessions

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/subsessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "step_ubos",
    "label": "Juan Garcia - UBO",
    "metadata": {
      "ownership_percentage": 25
    }
  }'

Response Format

{
  "status": "success",
  "data": {
    "subsession_id": "770e8400-e29b-41d4-a716-446655440003",
    "access_token": "880e8400-e29b-41d4-a716-446655440004",
    "access_link": "https://kyc.legaltalent.ai/public/sessions/880e8400-e29b-41d4-a716-446655440004",
    "workflow_id": "ubo-verification-workflow",
    "status": "active",
    "label": "Juan Garcia - UBO",
    "expires_at": 1732278600,
    "created_at": "2024-11-22T10:30:00Z"
  }
}

List Subsessions

Get all subsessions for a parent session with completion status.

Endpoint

GET /kyc/sessions/{session_id}/subsessions

Request Example

curl https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/subsessions \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "subsessions": [
      {
        "subsession_id": "770e8400-e29b-41d4-a716-446655440003",
        "access_token": "880e8400-e29b-41d4-a716-446655440004",
        "access_link": "https://kyc.legaltalent.ai/public/sessions/880e8400-...",
        "status": "completed",
        "workflow_id": "ubo-verification-workflow",
        "label": "Juan Garcia - UBO",
        "created_at": "2024-11-22T10:30:00Z",
        "expires_at": 1732278600,
        "completed_at": "2024-11-22T11:00:00Z"
      },
      {
        "subsession_id": "770e8400-e29b-41d4-a716-446655440005",
        "access_token": "880e8400-e29b-41d4-a716-446655440006",
        "access_link": "https://kyc.legaltalent.ai/public/sessions/880e8400-...",
        "status": "active",
        "workflow_id": "ubo-verification-workflow",
        "label": "Maria Lopez - UBO",
        "created_at": "2024-11-22T10:35:00Z",
        "expires_at": 1732278600
      }
    ],
    "total": 2,
    "completed": 1,
    "pending": 1
  }
}

Regenerate Subsession Link

Generate a new access link for a subsession if the original was lost or compromised.

Endpoint

POST /kyc/sessions/{session_id}/subsessions/{subsession_id}/regenerate-link

Request Example

curl -X POST https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/subsessions/770e8400-e29b-41d4-a716-446655440003/regenerate-link \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "subsession_id": "770e8400-e29b-41d4-a716-446655440003",
    "access_token": "990e8400-e29b-41d4-a716-446655440007",
    "access_link": "https://kyc.legaltalent.ai/public/sessions/990e8400-e29b-41d4-a716-446655440007",
    "expires_at": 1732278600
  }
}

Delete Subsession

Remove a subsession from a parent session.

Endpoint

DELETE /kyc/sessions/{session_id}/subsessions/{subsession_id}

Request Example

curl -X DELETE https://kyc.legaltalent.ai/kyc/sessions/660e8400-e29b-41d4-a716-446655440001/subsessions/770e8400-e29b-41d4-a716-446655440003 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "status": "success",
  "data": {
    "subsession_id": "770e8400-e29b-41d4-a716-446655440003",
    "deleted": true
  }
}

Typical Workflow

Create Session: Create a session linked to a workflow
Share Link: Send the access_link to the end user
User Completes Steps: User uploads documents and fills forms via public API
Subsessions (if applicable): User creates subsessions for UBOs/submerchants via the public API
Process Session: Call /process endpoint when session is completed
Review Results: Check processing_results for automatic decision
Final Decision: Update status to approved or rejected if manual review needed

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

​Overview

​Endpoints

​Authentication

​Create Session

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​List Sessions

​Endpoint

​Query Parameters

​Request Example

​Response Format

​Summary Statistics

​Response Format

​Process Session

​Endpoint

​Request Example

​Response Format

​Processing Results Fields

​Update Session Status

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​Generate Access Link

​Endpoint

​Request Example

​Response Format

​Run Validation Checks

​Endpoint

​Request Example

​Response Format

​Get Document URL

​Endpoint

​Request Example

​Response Format

​Delete Session

​Endpoint

​Request Example

​Response Format

​Session Statuses

​Step Statuses

​Status Codes

​Subsessions

​Create Subsession

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​List Subsessions

​Endpoint

​Request Example

​Response Format

​Regenerate Subsession Link

​Endpoint

​Request Example

​Response Format

​Delete Subsession

​Endpoint

​Request Example

​Response Format

​Typical Workflow

Overview

Endpoints

Authentication

Create Session

Endpoint

Request Body Parameters

Request Example

Response Format

List Sessions

Endpoint

Query Parameters

Request Example

Response Format

Summary Statistics

Response Format

Process Session

Endpoint

Request Example

Response Format

Processing Results Fields

Update Session Status

Endpoint

Request Body Parameters

Request Example

Response Format

Generate Access Link

Endpoint

Request Example

Response Format

Run Validation Checks

Endpoint

Request Example

Response Format

Get Document URL

Endpoint

Request Example

Response Format

Delete Session

Endpoint

Request Example

Response Format

Session Statuses

Step Statuses

Status Codes

Subsessions

Create Subsession

Endpoint

Request Body Parameters

Request Example

Response Format

List Subsessions

Endpoint

Request Example

Response Format

Regenerate Subsession Link

Endpoint

Request Example

Response Format

Delete Subsession

Endpoint

Request Example

Response Format

Typical Workflow