Skip to main content

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.

All API requests require authentication using Bearer tokens. The token is sent in the Authorization header of every request.

​
Header Format

All authenticated requests must include the following header: 
Authorization: Bearer <token>
The token can be either:
  • JWT Token: An ID token from your authentication provider (Cognito)
  • API Key: A service-to-service API key generated via the auth service

​
Token Types

​
JWT Tokens (User Authentication)

JWT tokens are issued when users log in through your authentication provider. These tokens are temporary and expire after a set period (typically 1 hour). When to use: Web applications, mobile apps, user-facing integrations

​
API Keys (Machine-to-Machine)

API keys are permanent credentials for server-to-server integrations. They are generated via the auth service and associated with a specific role. When to use: Backend services, automated integrations, scheduled jobs

​
Example Requests

​
Using JWT Token

curl -X POST https://stg.kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {"full_name": "John Doe"},
    "list_name": "ofac"
  }'

​
Using API Key

curl -X POST https://stg.kyc.legaltalent.ai/kyc \
  -H "Authorization: Bearer sk_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {"full_name": "John Doe"},
    "list_name": "ofac"
  }'

​
Token Validation

The authorization service automatically:
  • Validates the token format and signature
  • Extracts tenant identification from the token
  • Verifies required permissions for the requested operation
  • Passes tenant context to the backend Lambda functions
You do not need to include tenant_id in request bodies - it is automatically extracted from your token.

​
Permissions

Each token is associated with specific permissions following the resource:action pattern. The required permission varies by endpoint:

​
KYC Operations

EndpointMethodRequired PermissionDescription
/kycPOSTkyc:createInitiate a new KYC check
/kyc/{job_id}GETkyc:readView KYC check results
/exports/{jobId}GETkyc:exportExport KYC results (PDF)
/kyc/adverse-mediaPOSTkyc:createPerform adverse media check
/kyc/web-validationPOSTkyc:createValidate website URLs
/kyc/cryptoPOSTkyc:createCheck cryptocurrency wallets
/kyc/documents/{type}POSTkyc:createExtract document data
/kyc/jobsPOSTkyc:createCreate batch job
/kyc/jobs/{job_id}GETkyc:readGet batch job status
/kyc/workflowsPOSTkyc:createCreate workflow
/kyc/workflowsGETkyc:readList workflows
/kyc/workflows/{id}GETkyc:readGet workflow details
/kyc/workflows/{id}PUTkyc:createUpdate workflow
/kyc/workflows/{id}DELETEkyc:createDelete workflow
/kyc/sessionsPOSTkyc:createCreate session
/kyc/sessionsGETkyc:readList sessions
/kyc/sessions/{id}GETkyc:readGet session details
/kyc/sessions/{id}PATCHkyc:createUpdate session status
/kyc/sessions/{id}DELETEkyc:createDelete session

​
Watchlist Operations

EndpointMethodRequired PermissionDescription
/kyc/watchlistsPOSTwatchlist:createCreate a new watchlist
/kyc/watchlistsGETwatchlist:listList all watchlists
/kyc/watchlists/{id}GETwatchlist:readGet watchlist details
/kyc/watchlists/{id}PATCHwatchlist:updateUpdate watchlist config
/kyc/watchlists/{id}DELETEwatchlist:deleteDelete a watchlist
/kyc/watchlists/{id}/subjectsPOSTwatchlist:updateAdd subject to watchlist
/kyc/watchlists/{id}/subjects/batchPOSTwatchlist:updateBatch add subjects
/kyc/watchlists/{id}/subjects/{subject_id}DELETEwatchlist:updateRemove subject

​
Usage & Monitoring

EndpointMethodRequired PermissionDescription
/kyc/usageGETusage:readView usage metrics
/healthGETNoneBasic health check (public)
/health/readyGEThealth:readiness_checkReadiness check with dependencies

​
Tenant Management

EndpointMethodRequired PermissionDescription
/kyc/tenantsPOSTtenant:manageCreate tenant (admin)
/kyc/tenants/meGETtenant:readGet own tenant configuration
/kyc/tenants/{id}GETtenant:manageGet tenant details (admin)
/kyc/tenants/{id}PUTtenant:manageUpdate tenant (admin)
/kyc/tenants/{id}DELETEtenant:manageDelete tenant (admin)
/kyc/tenants/me/notification-channelsPATCHtenant:readUpdate own notification channels
/kyc/tenants/{id}/notification-channelsPATCHtenant:manageUpdate notification channels (admin)
/kyc/tenants/me/keywordsGETkeywords:readGet own keywords
/kyc/tenants/me/keywordsPATCHkeywords:updateUpdate own keywords
/kyc/tenants/{id}/keywordsGETkeywords:readGet keywords (admin)
/kyc/tenants/{id}/keywordsPATCHkeywords:updateUpdate keywords (admin)
/kyc/tenants/me/industriesGETindustries:readGet own industries
/kyc/tenants/me/industriesPATCHindustries:updateUpdate own industries
/kyc/tenants/{id}/industriesGETindustries:readGet industries (admin)
/kyc/tenants/{id}/industriesPATCHindustries:updateUpdate industries (admin)
/kyc/tenants/{id}/billingPATCHtenant:manageUpdate billing (admin)

​
Error Responses

​
401 Unauthorized

{
  "message": "Unauthorized"
}
This occurs when:
  • The Authorization header is missing
  • The token format is invalid
  • The token has expired (JWT tokens only)

​
403 Forbidden

{
  "message": "User is not authorized to perform this action"
}
This occurs when:
  • The token is valid but lacks required permissions
  • The token’s associated role doesn’t grant access to the resource

​
Getting API Keys

To generate an API key for machine-to-machine authentication:
  1. Contact your account administrator
  2. Provide the intended use case and required permissions
  3. The API key will be generated with appropriate role-based permissions
For security, API keys should be:
  • Stored securely (environment variables, secrets manager)
  • Never committed to version control
  • Rotated periodically
  • Revoked immediately if compromised