Prompt
REST API for customer due diligence
Latest observation
Oct 29, 2026
OpenAI APIWeb search: off
Here’s a practical REST API design for Customer Due Diligence (CDD). It covers onboarding, identity/KYC, risk scoring, screening, review, and auditability.
Core resources
- customers — customer profile and case anchor
- checks — KYC/CDD checks run against a customer
- documents — identity/address/business documents
- screenings — sanctions/PEP/adverse media screening results
- risk-scores — calculated risk assessments
- reviews — manual compliance reviews and decisions
- audit-events — immutable activity log
Suggested API surface
1) Create a customer
POST /v1/customers
{
"type": "individual",
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1990-04-21",
"countryOfResidence": "GB",
"email": "jane.doe@example.com",
"phone": "+447700900123",
"address": {
"line1": "10 High Street",
"city": "London",
"postalCode": "SW1A 1AA",
"country": "GB"
}
}
Response:
{
"id": "cust_123",
"status": "pending_due_diligence",
"createdAt": "2026-10-29T10:00:00Z"
}
2) Upload a document
POST /v1/customers/{customerId}/documents
{
"type": "passport",
"countryOfIssue": "GB",
"documentNumber": "123456789",
"expiresAt": "2031-06-30",
"fileId": "file_abc123"
}
3) Trigger a CDD check
POST /v1/customers/{customerId}/checks
{
"checkTypes": ["identity", "address", "sanctions", "pep", "adverse_media", "risk_assessment"],
"forceRefresh": true
}
Response:
{
"checkId": "chk_456",
"status": "in_progress"
}
4) Get check status/results
GET /v1/customers/{customerId}/checks/{checkId}
Response:
{
"id": "chk_456",
"customerId": "cust_123",
"status": "completed",
"results": [
{
"type": "sanctions",
"status": "clear",
"matched": false
},
{
"type": "pep",
"status": "review_required",
"matched": true,
"details": {
"matchConfidence": 0.92,
"source": "external_screening_provider"
}
}
],
"completedAt": "2026-10-29T10:03:00Z"
}
5) Retrieve risk score
GET /v1/customers/{customerId}/risk-score
Response:
{
"customerId": "cust_123",
"score": 72,
"band": "high",
"reasons": [
"PEP match",
"Non-resident country",
"Document nearing expiry"
],
"calculatedAt": "2026-10-29T10:03:10Z"
}
6) Create a manual review case
POST /v1/customers/{customerId}/reviews
{
"reason": "pep_match",
"assignedTo": "analyst_007",
"notes": "Potential false positive; verify source of wealth."
}
Response:
{
"id": "rev_789",
"status": "open"
}
7) Approve / reject / request more info
POST /v1/customers/{customerId}/reviews/{reviewId}/decision
{
"decision": "request_more_info",
"notes": "Please provide a second proof of address document."
}
Possible decisions:
approverejectrequest_more_info
8) Update customer status
PATCH /v1/customers/{customerId}
{
"status": "approved"
}
Status model
Typical customer lifecycle:
draftpending_due_diligenceunder_reviewapprovedrejectedrestrictedclosed
Recommended field set for CDD
Individual
- Name
- DOB
- Nationality
- Country of residence
- Address history
- Government ID details
- Occupation / employer
- Source of funds / source of wealth
- Expected transaction behavior
Business
- Legal name
- Registration number
- Incorporation country
- Registered address
- Directors / beneficial owners
- Ownership structure
- Nature of business
- Expected activity
- UBO documents
Best practices
- Use async processing for screening and risk scoring.
- Keep an immutable audit trail for every change.
- Support webhooks for status changes:
customer.approvedcustomer.rejectedcheck.completedreview.assigned
- Version your API:
/v1/... - Return clear error codes:
400validation error401unauthorized403forbidden404not found409conflict422compliance rule failed429rate limit500internal error
Example webhook
POST /webhooks/cdd
{
"event": "check.completed",
"timestamp": "2026-10-29T10:03:00Z",
"data": {
"customerId": "cust_123",
"checkId": "chk_456",
"status": "completed"
}
}
If you want, I can also provide:
- a full OpenAPI 3.0 spec,
- a database schema, or
- a Swagger-ready YAML for this CDD API.