> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

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

<ParamFields>
  <ParamField name="name" type="string" required description="Name of the customer (individual or company name)" />

  <ParamField name="client_id" type="string" description="External ID from your system (used to auto-link sessions)" />

  <ParamField name="entity_type" type="string" description="Type of entity: 'individual' or 'company' (default: 'individual')" />

  <ParamField name="email" type="string" description="Customer email address" />

  <ParamField name="phone" type="string" description="Customer phone number" />

  <ParamField name="website" type="string" description="Customer website URL" />

  <ParamField name="document_id" type="string" description="Identity document number" />

  <ParamField name="tax_id" type="string" description="Tax identification number (RUT, CUIT, EIN, etc.)" />

  <ParamField name="country" type="string" description="ISO 3166-1 alpha-2 country code" />

  <ParamField name="notes" type="string" description="Internal notes about the customer" />
</ParamFields>

### Request Example

```bash theme={null}
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

```json theme={null}
{
  "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

<ParamFields>
  <ParamField query="status" type="string" description="Filter by status: 'active' or 'inactive'" />

  <ParamField query="entity_type" type="string" description="Filter by entity type: 'individual' or 'company'" />

  <ParamField query="search" type="string" description="Search in name, client_id, document_id, tax_id, website, email" />

  <ParamField query="risk_level" type="string" description="Filter by risk level: 'low', 'medium', 'high', 'critical'" />

  <ParamField query="limit" type="integer" description="Number of results per page (default: 50, max: 100)" />

  <ParamField query="next_key" type="string" description="Pagination token from previous response" />
</ParamFields>

### Request Example

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

### Response Format

```json theme={null}
{
  "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

```bash theme={null}
curl https://kyc.legaltalent.ai/customers/550e8400-e29b-41d4-a716-446655440000/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Format

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<ParamFields>
  <ParamField name="watchlist_id" type="string" description="Existing watchlist ID to add the customer to (optional)" />

  <ParamField name="watchlist_name" type="string" description="Name for a new watchlist if not using existing (optional)" />

  <ParamField name="check_frequency" type="string" description="How often to check: 'daily', 'weekly', 'on_update' (default: 'daily')" />

  <ParamField name="include_ubos" type="boolean" description="Include UBOs in monitoring (default: true)" />

  <ParamField name="include_directors" type="boolean" description="Include directors in monitoring (default: false)" />
</ParamFields>

### Request Example

```bash theme={null}
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

```json theme={null}
{
  "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`:

```bash theme={null}
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                              |