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

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.

Endpoint

GET /kyc/sessions

Query Parameters

Request Example

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

Response Format

{
  "status": "success",
  "data": {
    "sessions": [
      {
        "session_id": "660e8400-e29b-41d4-a716-446655440001",
        "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
        "workflow_name": "Basic KYC",
        "status": "active",
        "current_step_index": 1,
        "total_steps": 3,
        "progress_percent": 33,
        "expires_at": 1732278600,
        "metadata": {
          "user_email": "user@example.com",
          "user_name": "John Doe"
        },
        "created_at": "2024-11-22T10:30:00Z",
        "updated_at": "2024-11-22T10:35:00Z"
      }
    ],
    "next_key": "eyJzZXNzaW9uX2lkIjoiNjYwZTg0MDA..."
  }
}

Get Session Details

Retrieve detailed information about a specific session.

Endpoint

GET /kyc/sessions/{session_id}

Request Example

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"
        }
      }
    ],
    "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

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

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

​Get Session Details

​Endpoint

​Request Example

​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

​Typical Workflow

Overview

Endpoints

Authentication

Create Session

Endpoint

Request Body Parameters

Request Example

Response Format

List Sessions

Endpoint

Query Parameters

Request Example

Response Format

Get Session Details

Endpoint

Request Example

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

Typical Workflow