Risk Assessment API¶

Assess the risk level of an identity based on multiple data sources and signals.

Endpoint¶

POST /api/v1/assess-risk

Authentication¶

Requires X-API-Key header with your API key.

Request Body¶

{
  "email": "user@example.com",
  "phone_number": "+15551234567",
  "full_name": "John Doe",
  "date_of_birth": "1990-01-15",
  "ip_address": "192.168.1.1",
  "device_fingerprint": "abc123..."
}

Field	Type	Required	Description
`email`	string	Yes	User's email address
`phone_number`	string	Yes	Phone number in E.164 format
`full_name`	string	Yes	User's full legal name
`date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`ip_address`	string	No	User's IP address
`device_fingerprint`	string	No	Device fingerprint for fraud detection

Response¶

{
  "risk_score": 15,
  "risk_level": "low",
  "signals": {
    "email_verified": true,
    "phone_verified": true,
    "name_match": true,
    "sanctions_check": "clear",
    "pep_check": "clear",
    "velocity_check": "pass"
  },
  "recommendations": [
    "APPROVE"
  ],
  "assessed_at": "2024-01-15T10:30:00Z"
}

Response Fields¶

Field	Type	Description
`risk_score`	integer	Risk score from 0-100 (lower is better)
`risk_level`	string	`low`, `medium`, `high`, or `critical`
`signals`	object	Individual risk signals evaluated
`recommendations`	array	Suggested actions: `APPROVE`, `REVIEW`, `REJECT`
`assessed_at`	string	ISO 8601 timestamp

Risk Levels¶

Level	Score Range	Description
`low`	0-25	Low risk, safe to proceed
`medium`	26-50	Some risk signals, review recommended
`high`	51-75	Significant risk, manual review required
`critical`	76-100	High risk, rejection recommended

Signals¶

Signal	Description
`email_verified`	Email exists and is deliverable
`phone_verified`	Phone number is valid and active
`name_match`	Name matches across data sources
`sanctions_check`	OFAC/sanctions list check result
`pep_check`	Politically Exposed Person check
`velocity_check`	Unusual activity patterns

Example¶

cURLPython

curl -X POST https://api.circuitkyc.com/api/v1/assess-risk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "email": "john.doe@example.com",
    "phone_number": "+15551234567",
    "full_name": "John Doe",
    "date_of_birth": "1990-01-15"
  }'

from circuit_kyc import CircuitKYC

client = CircuitKYC(api_key="sk_live_your_api_key")

result = client.assess_risk(
    email="john.doe@example.com",
    phone_number="+15551234567",
    full_name="John Doe",
    date_of_birth="1990-01-15"
)

if result.risk_level == "low":
    print("Safe to proceed")
elif result.risk_level in ["high", "critical"]:
    print("Manual review required")

Credit Cost¶

5 credits per request.

Rate Limits¶

Sandbox: 75 requests/minute
Starter: 300 requests/minute
Growth: 1,500 requests/minute
Enterprise: 6,000 requests/minute