Customers - KYC API Documentation

Manage customer/merchant records for your tenant. Customers aggregate all KYC sessions, organization structure, risk profiles, and monitoring status in one place.

Overview

Customers represent the end clients/merchants of your platform. Each customer:

Groups Sessions: All KYC sessions for the same entity in one place
Tracks Organization: UBOs, shareholders, directors, and representatives
Calculates Risk: Dynamic risk scoring based on session history
Enables Monitoring: Add customers to watchlists for ongoing screening

Endpoints

Method	Endpoint	Description
`POST`	`/customers`	Create a new customer
`GET`	`/customers`	List customers (paginated, with filters)
`GET`	`/customers/{id}`	Get customer details
`PATCH`	`/customers/{id}`	Update customer
`DELETE`	`/customers/{id}`	Deactivate customer
`GET`	`/customers/{id}/sessions`	Get customer’s sessions
`GET`	`/customers/{id}/organization`	Get organization structure
`GET`	`/customers/{id}/risk-profile`	Get/recalculate risk profile
`POST`	`/customers/{id}/monitor`	Add to watchlist monitoring

Authentication

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

Create Customer

Create a new customer record.

Endpoint

POST /customers

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/customers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "client_id": "merchant_12345",
    "entity_type": "company",
    "website": "https://acme.com",
    "tax_id": "12-3456789",
    "country": "US"
  }'

Response Format

{
  "status": "success",
  "data": {
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "client_id": "merchant_12345",
    "name": "Acme Corporation",
    "entity_type": "company",
    "status": "active",
    "website": "https://acme.com",
    "tax_id": "12-3456789",
    "country": "US",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

List Customers

Retrieve all customers for your tenant with pagination and filtering.

Endpoint

GET /customers

Query Parameters

Request Example

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

Response Format

{
  "status": "success",
  "data": {
    "customers": [
      {
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "tenant_id": "tenant123",
        "client_id": "merchant_12345",
        "name": "Acme Corporation",
        "entity_type": "company",
        "status": "active",
        "website": "https://acme.com",
        "country": "US",
        "risk_level": "low",
        "sessions_count": 5,
        "is_monitored": true,
        "created_at": "2024-11-22T10:30:00Z",
        "updated_at": "2024-11-22T12:00:00Z",
        "last_activity_at": "2024-11-22T12:00:00Z"
      }
    ],
    "count": 1,
    "next_key": null
  }
}

Get Customer Sessions

Retrieve all KYC sessions for a specific customer.

Endpoint

GET /customers/{customer_id}/sessions

Request Example

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

Response Format

{
  "status": "success",
  "data": {
    "sessions": [
      {
        "session_id": "660e8400-e29b-41d4-a716-446655440001",
        "workflow_id": "770e8400-e29b-41d4-a716-446655440002",
        "workflow_name": "Merchant Onboarding",
        "status": "approved",
        "created_at": "2024-11-22T10:30:00Z",
        "completed_at": "2024-11-22T11:00:00Z"
      }
    ],
    "count": 1
  }
}

Get Organization Structure

Retrieve the organizational structure (UBOs, shareholders, directors) for a customer.

Endpoint

GET /customers/{customer_id}/organization

Response Format

{
  "status": "success",
  "data": {
    "organization": {
      "root_entity": "Acme Corporation",
      "members": [
        {
          "member_id": "mem_123",
          "name": "John Smith",
          "role": "ubo",
          "ownership_percentage": 60,
          "entity_type": "individual",
          "verified": true,
          "session_id": "sess_abc"
        },
        {
          "member_id": "mem_456",
          "name": "Holdings LLC",
          "role": "shareholder",
          "ownership_percentage": 40,
          "entity_type": "company",
          "verified": false
        }
      ],
      "source": "extracted"
    },
    "summary": {
      "total_members": 2,
      "ubo_count": 1,
      "unverified_count": 1,
      "ownership_coverage": 100,
      "is_complete": false
    },
    "unverified_members": [
      {
        "member_id": "mem_456",
        "name": "Holdings LLC",
        "role": "shareholder"
      }
    ]
  }
}

Get Risk Profile

Get or recalculate the risk profile for a customer.

Endpoint

GET /customers/{customer_id}/risk-profile

Response Format

{
  "status": "success",
  "data": {
    "overall_score": 25.5,
    "risk_level": "low",
    "factors": [
      {
        "factor_id": "sessions_completion",
        "name": "Session History",
        "score": 10,
        "weight": 0.15,
        "details": "Approval rate: 100%"
      },
      {
        "factor_id": "watchlist_matches",
        "name": "Watchlist Matches",
        "score": 0,
        "weight": 0.25,
        "details": "No watchlist alerts"
      }
    ],
    "compliance_gaps": [],
    "last_evaluated": "2024-11-22T12:00:00Z"
  }
}

Add to Monitoring

Add the customer to watchlist monitoring for ongoing screening.

Endpoint

POST /customers/{customer_id}/monitor

Request Body Parameters

Request Example

curl -X POST https://kyc.legaltalent.ai/customers/550e8400-e29b-41d4-a716-446655440000/monitor \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "check_frequency": "daily",
    "include_ubos": true
  }'

Response Format

{
  "status": "success",
  "data": {
    "is_monitored": true,
    "watchlists": [
      {
        "watchlist_id": "wl_123",
        "watchlist_name": "Customer Acme Corporation",
        "subject_id": "subj_456",
        "status": "active",
        "added_at": "2024-11-22T12:00:00Z"
      }
    ],
    "total_alerts": 0
  }
}

Session Creation with Customer

When creating a session, you can link it to a customer using customer_id or client_id:

curl -X POST https://kyc.legaltalent.ai/kyc/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_123",
    "client_id": "merchant_12345",
    "metadata": {
      "user_name": "John Doe",
      "user_email": "john@acme.com"
    }
  }'

If a customer with the client_id doesn’t exist, it will be auto-created.

Status Codes

Code	Description
200	Success
201	Created - Customer created successfully
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
404	Not Found - Customer not found
409	Conflict - Customer with client_id already exists
500	Internal Server Error

​Overview

​Endpoints

​Authentication

​Create Customer

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​List Customers

​Endpoint

​Query Parameters

​Request Example

​Response Format

​Get Customer Sessions

​Endpoint

​Request Example

​Response Format

​Get Organization Structure

​Endpoint

​Response Format

​Get Risk Profile

​Endpoint

​Response Format

​Add to Monitoring

​Endpoint

​Request Body Parameters

​Request Example

​Response Format

​Session Creation with Customer

​Status Codes

Overview

Endpoints

Authentication

Create Customer

Endpoint

Request Body Parameters

Request Example

Response Format

List Customers

Endpoint

Query Parameters

Request Example

Response Format

Get Customer Sessions

Endpoint

Request Example

Response Format

Get Organization Structure

Endpoint

Response Format

Get Risk Profile

Endpoint

Response Format

Add to Monitoring

Endpoint

Request Body Parameters

Request Example

Response Format

Session Creation with Customer

Status Codes