Create Watchlist - KYC API Documentation

Endpoint

POST /kyc/watchlists

Authentication

Requires watchlist:create permission.

Request Body

Webhook URLs and notification emails are configured at the tenant level, not per-watchlist. Contact support to configure your notification channels.

Request Example

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "check_frequency": "daily",
    "lists_to_monitor": ["ofac", "un"],
    "tags": ["compliance", "high-priority"]
  }'

Additional Request Examples

Watchlist with Initial Subjects

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendor Monitoring",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "priority"],
        "session_id": "sess_abc123"
      },
      {
        "full_name": "Acme Corporation",
        "identifier": "TAX-987654",
        "identifier_type": "tax_id",
        "tags": ["vendor"]
      }
    ],
    "lists_to_monitor": ["ofac", "un", "eu"],
    "check_frequency": "weekly",
    "status": "active",
    "tags": ["vendors", "2024"]
  }'

Watchlist with Alerts

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Executive Monitoring",
    "check_frequency": "daily",
    "lists_to_monitor": ["ofac", "un"],
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    }
  }'

Notification webhooks and emails are configured at the tenant level. The alert_config only controls when to send alerts, not where.

Crypto Wallet Monitoring

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Crypto Wallets",
    "subjects": [
      {
        "full_name": "Bitcoin Wallet 1",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet"
      }
    ],
    "lists_to_monitor": ["ofac"],
    "check_frequency": "daily"
  }'

Usage Examples

Python

import requests

url = "https://stg.kyc.legaltalent.ai/kyc/watchlists"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

# Simple watchlist
payload = {
    "name": "High Risk Customers",
    "check_frequency": "daily",
    "lists_to_monitor": ["ofac", "un"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

# Watchlist with subjects
payload = {
    "name": "Vendor Monitoring",
    "subjects": [
        {
            "full_name": "John Doe",
            "identifier": "12345678",
            "identifier_type": "document"
        },
        {
            "full_name": "Acme Corporation",
            "identifier": "TAX-987654",
            "identifier_type": "tax_id"
        }
    ],
    "lists_to_monitor": ["ofac", "un", "eu"],
    "check_frequency": "weekly",
    "status": "active"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

# Watchlist with alerts
payload = {
    "name": "Executive Monitoring",
    "check_frequency": "daily",
    "lists_to_monitor": ["ofac", "un"],
    "alert_config": {
        "on_new_match": True,
        "on_status_change": True
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript

const url = 'https://stg.kyc.legaltalent.ai/kyc/watchlists';

// Simple watchlist
const simplePayload = {
  name: 'High Risk Customers',
  check_frequency: 'daily',
  lists_to_monitor: ['ofac', 'un']
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(simplePayload)
})
  .then(response => response.json())
  .then(data => console.log(data));

// Watchlist with subjects
const payloadWithSubjects = {
  name: 'Vendor Monitoring',
  subjects: [
    {
      full_name: 'John Doe',
      identifier: '12345678',
      identifier_type: 'document'
    },
    {
      full_name: 'Acme Corporation',
      identifier: 'TAX-987654',
      identifier_type: 'tax_id'
    }
  ],
  lists_to_monitor: ['ofac', 'un', 'eu'],
  check_frequency: 'weekly',
  status: 'active'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payloadWithSubjects)
})
  .then(response => response.json())
  .then(data => console.log(data));

// Watchlist with alerts
const payloadWithAlerts = {
  name: 'Executive Monitoring',
  check_frequency: 'daily',
  lists_to_monitor: ['ofac', 'un'],
  alert_config: {
    on_new_match: true,
    on_status_change: true
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payloadWithAlerts)
})
  .then(response => response.json())
  .then(data => console.log(data));

Response

Success Response (201 Created)

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "High Risk Customers",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "priority"],
        "session_id": "sess_abc123",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763814600
      }
    ],
    "tags": ["compliance", "high-priority"],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "last_checked_at": null,
    "next_check_due": 1732278600000,
    "last_results": null,
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
`watchlist_id`	string	Unique identifier for the watchlist
`tenant_id`	string	Your tenant identifier
`name`	string	Watchlist name
`subjects`	array	List of subjects being monitored
`lists_to_monitor`	array	Lists to check against
`check_frequency`	string	Screening frequency
`last_checked_at`	string/null	Last check timestamp (ISO 8601)
`next_check_due`	number/null	Next check timestamp (Unix milliseconds)
`last_results`	object/null	Most recent screening results
`alert_config`	object	Alert configuration
`status`	string	Watchlist status (`active` or `paused`)
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Error Responses

400 Bad Request

{
  "status": "error",
  "error": {
    "type": "ValidationError",
    "message": "Watchlist name is required",
    "code": "VALIDATION_ERROR"
  }
}

Common validation errors:

Missing or empty name field
Invalid check_frequency value
Invalid lists_to_monitor values
Invalid subject data

403 Forbidden

{
  "message": "User is not authorized to perform this action"
}

Your token lacks the watchlist:create permission.

Subject Fields

When adding subjects during creation:

Field	Type	Required	Description
`full_name`	string	Yes	Full name of the subject
`identifier`	string	No	Document ID, wallet address, email, etc.
`identifier_type`	string	No	Type: “document”, “wallet”, “email”, “tax_id”, etc.
`tags`	array	No	Custom tags for categorization and filtering
`session_id`	string	No	Session ID if subject was created during onboarding

Best Practices

Start Empty, Add Later

You can create a watchlist without subjects and add them later using the Add Subjects endpoint. This is useful when setting up infrastructure before onboarding subjects.

Choose the Right Frequency

Daily: High-risk entities, regulatory requirements, active monitoring
Weekly: Standard monitoring, cost optimization
On Update: Static lists, manual control, lowest cost

Configure Alerts from Start

Set up webhooks and email notifications when creating the watchlist to ensure you don’t miss critical alerts during the first screening cycle.

Select Relevant Lists

Only monitor lists relevant to your jurisdiction and risk profile:

US entities: Include ofac
International: Include un and eu
Uruguay PEPs: Include senaclaft_uy

Status Codes

Code	Description
201	Created - Watchlist created successfully
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
500	Internal Server Error

Next Steps

After creating a watchlist:

Add subjects to begin monitoring
Get watchlist details to verify configuration
Set up webhook endpoint to receive alerts
Monitor screening activity with the Usage API

​Endpoint

​Authentication

​Request Body

​Request Example

​Additional Request Examples

​Watchlist with Initial Subjects

​Watchlist with Alerts

​Crypto Wallet Monitoring

​Usage Examples

​Python

​JavaScript

​Response

​Success Response (201 Created)

​Response Fields

​Error Responses

​400 Bad Request

​403 Forbidden

​Subject Fields

​Best Practices

​Status Codes

​Next Steps

Endpoint

Authentication

Request Body

Request Example

Additional Request Examples

Watchlist with Initial Subjects

Watchlist with Alerts

Crypto Wallet Monitoring

Usage Examples

Python

JavaScript

Response

Success Response (201 Created)

Response Fields

Error Responses

400 Bad Request

403 Forbidden

Subject Fields

Best Practices

Status Codes

Next Steps