API Overview

Welcome

The KYC API provides comprehensive compliance screening for sanctions lists, PEPs (Politically Exposed Persons), and adverse media. Built for financial institutions, fintech companies, and any business requiring KYC/AML compliance.

Environments

The API is available in two client-accessible environments:

Staging

Base URL: https://stg.kyc.legaltalent.ai

Testing and integration development
Same features as production
Safe environment for experimentation

Production

Base URL: https://kyc.legaltalent.ai

Live operations
Production-grade SLAs
Full monitoring and alerting

Always use Staging for development and testing. Only use Production URLs with production credentials for live operations.

Base URLs

Environment	API Base URL
Staging	`https://stg.kyc.legaltalent.ai`
Production	`https://kyc.legaltalent.ai`

Rate Limiting

The API is protected by AWS WAF (Web Application Firewall) with intelligent rate limiting to ensure service availability and prevent abuse.

Rate Limits

Current Limit: 1,000 requests per 5 minutes per IP address

Rate limits apply per source IP address and are enforced at both Staging and Production environments.

Rate Limit Details

Metric	Value
Requests per window	1,000
Time window	5 minutes (300 seconds)
Enforcement	Per IP address
Response when exceeded	`429 Too Many Requests`

Rate Limit Headers

Responses include rate limit information in headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1732278600

Rate Limit Response

When you exceed the rate limit, you’ll receive:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again in 3 minutes.",
  "retry_after": 180
}

HTTP Status: 429 Too Many Requests

Best Practices for Rate Limits

Implement Exponential Backoff

When you receive a 429 response, implement exponential backoff:

import time

def make_request_with_backoff(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, ...)
        if response.status_code != 429:
            return response
        
        # Exponential backoff: 2^attempt seconds
        wait_time = 2 ** attempt
        time.sleep(wait_time)
    
    raise Exception("Rate limit exceeded after retries")

Batch Requests Efficiently

Use multi-list checks instead of multiple single-list requests:❌ Inefficient (3 requests):

POST /kyc { "list_name": "ofac" }
POST /kyc { "list_name": "un" }
POST /kyc { "list_name": "eu" }

✅ Efficient (1 request):

POST /kyc { "lists": ["ofac", "un", "eu"] }

Monitor Usage Metrics

Track your usage with the Usage API to stay within limits:

GET /kyc/usage?granularity=hour

Set up alerts when approaching 80% of your rate limit.

Distribute Load

For high-volume integrations:

Spread requests evenly over time
Avoid burst patterns at start of 5-minute windows
Plan your integration to stay within rate limits

Need Higher Limits?

If your use case requires higher rate limits, contact your account manager to discuss enterprise plans with:

Custom rate limits
Dedicated infrastructure
SLA guarantees
Priority support

WAF Protection

In addition to rate limiting, the API is protected by AWS WAF with:

OWASP Top 10 Protection

Protection against common web attacks including SQL injection, XSS, and remote code execution.

DDoS Mitigation

Automatic detection and blocking of distributed denial-of-service attacks.

Geo-Filtering

Optional geographic restrictions for enhanced security.

Bot Protection

Intelligent filtering of automated traffic and malicious bots.

Authentication

All API requests require authentication using Bearer tokens. See the Authentication guide for details on:

JWT tokens for user applications
API keys for server-to-server integrations
Permission model and RBAC
Token management best practices

API Features

List Screening

Real-time checks against OFAC, UN, EU, and SENACLAFT watchlists.

Adverse Media

AI-powered adverse media screening with risk scoring.

Watchlists

Automated ongoing monitoring with configurable alerts.

Export & Reporting

PDF report generation for compliance documentation.

Usage Tracking

Detailed usage metrics and analytics.

Health Check

Service health and availability monitoring.

Support

Documentation Issues: Contact your account manager
Technical Support: Available during business hours
Emergency Support: Available for production incidents

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

Welcome

Environments

Staging

Production

Base URLs

Rate Limiting

Rate Limits

Rate Limit Details

Rate Limit Headers

Rate Limit Response

Best Practices for Rate Limits

Need Higher Limits?

WAF Protection

OWASP Top 10 Protection

DDoS Mitigation

Geo-Filtering

Bot Protection

Authentication

API Features

List Screening

Adverse Media

Watchlists

Export & Reporting

Usage Tracking

Health Check

Support

​Welcome

​Environments

Staging

Production

​Base URLs

​Rate Limiting

​Rate Limits

​Rate Limit Details

​Rate Limit Headers

​Rate Limit Response

​Best Practices for Rate Limits

​Need Higher Limits?

​WAF Protection

OWASP Top 10 Protection

DDoS Mitigation

Geo-Filtering

Bot Protection

​Authentication

​API Features

List Screening

Adverse Media

Watchlists

Export & Reporting

Usage Tracking

Health Check

​Support

Welcome

Environments

Base URLs

Rate Limiting

Rate Limits

Rate Limit Details

Rate Limit Headers

Rate Limit Response

Best Practices for Rate Limits

Need Higher Limits?

WAF Protection

Authentication

API Features

Support