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
`POST`	`/public/sessions/{access_token}/subsessions`	Create a subsession
`GET`	`/public/sessions/{access_token}/subsessions`	List subsessions
`POST`	`/public/sessions/{access_token}/subsessions/{sub_id}/regenerate-link`	Regenerate subsession link

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);
}

Subsessions

Subsessions allow end users to create verification sessions for related parties (UBOs, submerchants, directors) during the main onboarding process. These are available when the workflow includes a subsession_collection step type.

Create Subsession

Create a new subsession for a related party (e.g., UBO, submerchant).

Endpoint

POST /public/sessions/{access_token}/subsessions

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/subsessions \
  -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": "880e8400-e29b-41d4-a716-446655440003",
    "access_token": "990e8400-e29b-41d4-a716-446655440004",
    "access_link": "https://kyc.legaltalent.ai/public/sessions/990e8400-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 created from the current session.

Endpoint

GET /public/sessions/{access_token}/subsessions

Request Example

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

Response Format

{
  "status": "success",
  "data": {
    "subsessions": [
      {
        "subsession_id": "880e8400-e29b-41d4-a716-446655440003",
        "workflow_name": "UBO Verification",
        "status": "completed",
        "access_link": "https://kyc.legaltalent.ai/public/sessions/990e8400-...",
        "label": "Juan Garcia - UBO",
        "expires_at": 1732278600,
        "created_at": "2024-11-22T10:30:00Z",
        "completed_at": "2024-11-22T11:00:00Z"
      },
      {
        "subsession_id": "880e8400-e29b-41d4-a716-446655440005",
        "workflow_name": "UBO Verification",
        "status": "active",
        "access_link": "https://kyc.legaltalent.ai/public/sessions/990e8400-...",
        "label": "Maria Lopez - UBO",
        "expires_at": 1732278600,
        "created_at": "2024-11-22T10:35:00Z"
      }
    ],
    "total_subsessions": 2,
    "max_subsessions": 5
  }
}

Regenerate Subsession Link

Generate a new access link for a subsession if the original was lost or needs to be refreshed.

Endpoint

POST /public/sessions/{access_token}/subsessions/{subsession_id}/regenerate-link

Request Example

curl -X POST https://kyc.legaltalent.ai/public/sessions/770e8400-e29b-41d4-a716-446655440002/subsessions/880e8400-e29b-41d4-a716-446655440003/regenerate-link

Response Format

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

Subsession Errors

400 Bad Request - Maximum Subsessions Reached

{
  "status": "error",
  "error": "Maximum number of subsessions reached for this step (5)"
}

400 Bad Request - Invalid Step Type

{
  "status": "error",
  "error": "Step 'step_1' is not a subsession_collection step"
}

404 Not Found - Subsession Not Found

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

JavaScript Integration Example - Subsessions

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

// Create a subsession for a UBO
async function createSubsession(stepId, label, metadata = {}) {
  const response = await fetch(`${baseUrl}/${accessToken}/subsessions`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      step_id: stepId,
      label: label,
      metadata: metadata
    })
  });
  
  const data = await response.json();
  if (data.status === 'success') {
    console.log("Subsession link:", data.data.access_link);
    return data.data;
  } else {
    throw new Error(data.error);
  }
}

// List all subsessions for the current session
async function listSubsessions() {
  const response = await fetch(`${baseUrl}/${accessToken}/subsessions`);
  const data = await response.json();
  return data.data;
}

// Regenerate subsession link
async function regenerateSubsessionLink(subsessionId) {
  const response = await fetch(
    `${baseUrl}/${accessToken}/subsessions/${subsessionId}/regenerate-link`,
    { method: "POST" }
  );
  
  const data = await response.json();
  return data.data;
}

// Example: Create subsessions for UBOs
async function handleUBOStep(stepId) {
  const ubos = [
    { name: "Juan Garcia", ownership: 25 },
    { name: "Maria Lopez", ownership: 35 },
    { name: "Carlos Ruiz", ownership: 40 }
  ];
  
  const subsessionLinks = [];
  
  for (const ubo of ubos) {
    const subsession = await createSubsession(
      stepId,
      `${ubo.name} - UBO`,
      { ownership_percentage: ubo.ownership }
    );
    
    subsessionLinks.push({
      name: ubo.name,
      link: subsession.access_link
    });
    
    console.log(`Created subsession for ${ubo.name}: ${subsession.access_link}`);
  }
  
  // Return links to share with UBOs
  return subsessionLinks;
}

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
Subsession Management: For subsession_collection steps, check max_subsessions before creating new ones
Subsession Completion: If require_completion_before_proceed is enabled on the step, all subsessions must be completed before the parent session can proceed

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

Documentation Index

​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

​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

​Subsession Errors

​400 Bad Request - Maximum Subsessions Reached

​400 Bad Request - Invalid Step Type

​404 Not Found - Subsession Not Found

​JavaScript Integration Example - Subsessions

​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

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

Subsession Errors

400 Bad Request - Maximum Subsessions Reached

400 Bad Request - Invalid Step Type

404 Not Found - Subsession Not Found

JavaScript Integration Example - Subsessions

Best Practices