Public Sessions - KYC API Documentation

Public endpoints for end users to access and interact with KYC onboarding sessions. These endpoints require no authentication - access is controlled via secure access tokens.

Overview

Public session endpoints allow end users to:

Access Sessions: View session state and workflow definition
Upload Documents: Upload required documents and selfies
Extract Data: Extract data from uploaded documents
Complete Steps: Mark steps as completed with form data

These endpoints are designed for frontend integration and require no authentication - access is controlled via the access token provided when creating the session.

Endpoints

Method	Endpoint	Description
`GET`	`/public/sessions/{access_token}`	Get session state
`GET`	`/public/sessions/{access_token}/workflow`	Get workflow definition
`POST`	`/public/sessions/{access_token}/upload`	Upload document
`POST`	`/public/sessions/{access_token}/extract`	Extract document data
`POST`	`/public/sessions/{access_token}/step/{step_id}/complete`	Complete a step

Authentication

No authentication required. Access is controlled via the access_token path parameter.

Get Session State

Retrieve the current state of a session including progress and uploaded documents.

Endpoint

GET /public/sessions/{access_token}

Request Example

curl https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002

Response Format

{
  "status": "success",
  "data": {
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "workflow_name": "Basic KYC",
    "status": "active",
    "current_step_index": 1,
    "total_steps": 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",
            "uploaded_at": "2024-11-22T10:32:00Z"
          }
        ]
      },
      {
        "step_id": "step_2",
        "status": "in_progress",
        "started_at": "2024-11-22T10:33:00Z"
      },
      {
        "step_id": "step_3",
        "status": "pending"
      }
    ],
    "expires_at": 1732278600,
    "created_at": "2024-11-22T10:30:00Z"
  }
}

Get Workflow Definition

Retrieve the workflow definition to know what steps and fields are required.

Endpoint

GET /public/sessions/{access_token}/workflow

Request Example

curl https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/workflow

Response Format

{
  "status": "success",
  "data": {
    "workflow_name": "Basic KYC",
    "description": "Standard KYC onboarding workflow",
    "total_steps": 3,
    "steps": [
      {
        "step_id": "step_1",
        "order": 1,
        "name": "ID Document",
        "type": "document_upload",
        "required_documents": ["id"]
      },
      {
        "step_id": "step_2",
        "order": 2,
        "name": "Selfie",
        "type": "selfie"
      },
      {
        "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
          }
        ]
      }
    ]
  }
}

Upload Document

Upload a document or selfie for a specific step.

Endpoint

POST /public/sessions/{access_token}/upload

Request Body Parameters

Request Example - ID Document

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/upload \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "step_1",
    "document_type": "id",
    "file_data": "base64_encoded_file_data...",
    "file_name": "passport.jpg",
    "mime_type": "image/jpeg"
  }'

Request Example - Selfie

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/upload \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "step_2",
    "document_type": "selfie",
    "file_data": "base64_encoded_selfie_data...",
    "file_name": "selfie.jpg",
    "mime_type": "image/jpeg"
  }'

Response Format

{
  "status": "success",
  "data": {
    "doc_id": "doc_abc123",
    "s3_key": "tenant123/660e8400-e29b-41d4-a716-446655440001/doc_abc123.jpg",
    "uploaded_at": "2024-11-22T10:32:00Z"
  }
}

Extract Document Data

Extract structured data from an uploaded document using OCR/AI.

Endpoint

POST /public/sessions/{access_token}/extract

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/extract \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "doc_abc123",
    "document_type": "passport"
  }'

Response Format

{
  "status": "success",
  "data": {
    "doc_id": "doc_abc123",
    "extracted_data": {
      "full_name": "JOHN DOE",
      "document_number": "AB1234567",
      "date_of_birth": "1985-03-15",
      "nationality": "US",
      "expiry_date": "2030-01-15",
      "gender": "M"
    },
    "confidence_scores": {
      "overall": 0.95,
      "full_name": 0.98,
      "document_number": 0.99,
      "date_of_birth": 0.92
    }
  }
}

Complete Step

Mark a step as completed, optionally with form data.

Endpoint

POST /public/sessions/{access_token}/step/{step_id}/complete

Path Parameters

Request Body Parameters

Request Example - Document Step

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/step/step_1/complete \
  -H "Content-Type: application/json" \
  -d '{}'

Request Example - Form Step

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/step/step_3/complete \
  -H "Content-Type: application/json" \
  -d '{
    "form_data": {
      "full_name": "John Doe",
      "date_of_birth": "1985-03-15",
      "email": "john@example.com"
    }
  }'

Response Format

{
  "status": "success",
  "data": {
    "step_id": "step_3",
    "status": "completed",
    "next_step_id": null,
    "session_completed": true
  }
}

Response Fields

Field	Description
`step_id`	The completed step ID
`status`	Step status (always “completed”)
`next_step_id`	ID of the next step, or null if this was the last step
`session_completed`	True if all steps are now completed

Error Responses

404 Not Found - Invalid Access Token

{
  "status": "error",
  "error": "Session not found or expired"
}

400 Bad Request - Invalid Step

{
  "status": "error",
  "error": "Step not found"
}

400 Bad Request - Invalid Document Type

{
  "status": "error",
  "error": "Document type not allowed for this step"
}

400 Bad Request - Missing Required Fields

{
  "status": "error",
  "error": "Invalid step data: Missing required field: full_name"
}

Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters or validation failed
404	Not Found - Invalid access token or step not found
500	Internal Server Error

JavaScript Integration Example

const accessToken = "770e8400-e29b-41d4-a716-446655440002";
const baseUrl = "https://kyc.legaltalent.ai/public/sessions";

// Get session state
async function getSessionState() {
  const response = await fetch(`${baseUrl}/${accessToken}`);
  const data = await response.json();
  return data.data;
}

// Get workflow definition
async function getWorkflow() {
  const response = await fetch(`${baseUrl}/${accessToken}/workflow`);
  const data = await response.json();
  return data.data;
}

// Upload document
async function uploadDocument(file, stepId, documentType) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = async () => {
      const base64Data = reader.result.split(',')[1];
      
      const response = await fetch(`${baseUrl}/${accessToken}/upload`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          step_id: stepId,
          document_type: documentType,
          file_data: base64Data,
          file_name: file.name,
          mime_type: file.type
        })
      });
      
      const data = await response.json();
      if (data.status === 'success') {
        resolve(data.data);
      } else {
        reject(new Error(data.error));
      }
    };
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

// Extract data from document
async function extractDocument(docId, documentType) {
  const response = await fetch(`${baseUrl}/${accessToken}/extract`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ 
      doc_id: docId,
      document_type: documentType 
    })
  });
  
  const data = await response.json();
  return data.data;
}

// Complete a step
async function completeStep(stepId, formData = null) {
  const response = await fetch(
    `${baseUrl}/${accessToken}/step/${stepId}/complete`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ form_data: formData })
    }
  );
  
  const data = await response.json();
  return data.data;
}

// Example: Complete onboarding flow
async function runOnboardingFlow() {
  // 1. Get workflow to know the steps
  const workflow = await getWorkflow();
  console.log("Workflow:", workflow.workflow_name);
  
  // 2. For each step, complete it
  for (const step of workflow.steps) {
    console.log(`Processing step: ${step.name}`);
    
    if (step.type === 'document_upload') {
      // Upload required documents
      // In real app: get file from user input
    } else if (step.type === 'selfie') {
      // Capture and upload selfie
    } else if (step.type === 'form_fill') {
      // Collect form data from user
      const formData = {
        full_name: "John Doe",
        date_of_birth: "1985-03-15"
      };
      await completeStep(step.step_id, formData);
    }
  }
  
  // 3. Check final state
  const session = await getSessionState();
  console.log("Session status:", session.status);
}

Best Practices

Security: Access tokens are UUIDs - share them securely with end users
Expiration: Check expires_at before allowing user actions
Error Handling: Handle expired sessions gracefully with user-friendly messages
File Validation: Validate file types and sizes client-side before upload
Progress Tracking: Use current_step_index and total_steps to show progress
Step Validation: The API validates required fields - handle validation errors in UI

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

​Overview

​Endpoints

​Authentication

​Get Session State

​Endpoint

​Request Example

​Response Format

​Get Workflow Definition

​Endpoint

​Request Example

​Response Format

​Upload Document

​Endpoint

​Request Body Parameters

​Request Example - ID Document

​Request Example - Selfie

​Response Format

​Extract Document Data

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​Complete Step

​Endpoint

​Path Parameters

​Request Body Parameters

​Request Example - Document Step

​Request Example - Form Step

​Response Format

​Response Fields

​Error Responses

​404 Not Found - Invalid Access Token

​400 Bad Request - Invalid Step

​400 Bad Request - Invalid Document Type

​400 Bad Request - Missing Required Fields

​Status Codes

​JavaScript Integration Example

​Best Practices

Overview

Endpoints

Authentication

Get Session State

Endpoint

Request Example

Response Format

Get Workflow Definition

Endpoint

Request Example

Response Format

Upload Document

Endpoint

Request Body Parameters

Request Example - ID Document

Request Example - Selfie

Response Format

Extract Document Data

Endpoint

Request Body Parameters

Request Example

Response Format

Complete Step

Endpoint

Path Parameters

Request Body Parameters

Request Example - Document Step

Request Example - Form Step

Response Format

Response Fields

Error Responses

404 Not Found - Invalid Access Token

400 Bad Request - Invalid Step

400 Bad Request - Invalid Document Type

400 Bad Request - Missing Required Fields

Status Codes

JavaScript Integration Example

Best Practices