Credit Risk API
AI-powered credit scoring for Buy Now Pay Later (BNPL) decisions with real-time risk analysis.
Overview
The Credit Risk API provides:
- Credit Scoring — AI-generated credit scores (FICO-equivalent)
- Risk Assessment — Risk level classification
- Credit Limits — Dynamic credit limit recommendations
- Decision Support — Automated approval/denial decisions
Base URL
https://api.huntrecht.com/api/v1/credit-risk
Required Scopes
| Scope | Permission |
|---|---|
credit:read | View credit scores |
credit:write | Request credit assessments |
Credit Score Tiers
| Score Range | Risk Level | Max Credit Limit | Interest Rate |
|---|---|---|---|
| 750-850 | Excellent | $100,000 | 5.0% - 7.0% |
| 700-749 | Good | $50,000 | 7.0% - 9.0% |
| 650-699 | Fair | $25,000 | 9.0% - 12.0% |
| 600-649 | Poor | $10,000 | 12.0% - 18.0% |
| Below 600 | High Risk | Declined | N/A |
Get Credit Score
GET /credit-risk/score
Retrieve a customer's credit score and risk assessment.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_id | string | Yes | Customer ID |
Example Request
credit = client.credit_risk.get_score(customer_id="cust_abc123")
Example Response
{
"data": {
"customer_id": "cust_abc123",
"score": 720,
"fico_equivalent": 720,
"risk_level": "low",
"max_credit_limit": 50000.00,
"recommended_terms": {
"installments": [6, 12, 24],
"interest_rate_range": [6.5, 10.0],
"max_order_amount": 25000.00
},
"credit_factors": [
{"factor": "payment_history", "impact": "positive", "score": 85},
{"factor": "credit_utilization", "impact": "positive", "score": 92},
{"factor": "account_age_months", "impact": "neutral", "score": 60},
{"factor": "recent_inquiries", "impact": "negative", "score": 45},
{"factor": "public_records", "impact": "positive", "score": 100}
],
"last_updated": "2026-01-10T08:00:00Z",
"next_update": "2026-02-10T08:00:00Z"
}
}
Request Credit Assessment
POST /credit-risk/assess
Request a new credit assessment for a specific amount or purpose.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | Yes | Customer ID |
amount | number | No | Requested credit amount |
purpose | string | No | Credit purpose (equipment_purchase, inventory, etc.) |
Example Request
assessment = client.credit_risk.assess({
"customer_id": "cust_abc123",
"amount": 10000.00,
"purpose": "equipment_purchase"
})
Example Response
{
"data": {
"assessment_id": "assess_123",
"customer_id": "cust_abc123",
"decision": "approved",
"approved_amount": 10000.00,
"interest_rate": 8.5,
"score": 720,
"risk_level": "low",
"terms": {
"installments_available": [6, 12, 24],
"monthly_payment_estimate": 868.00,
"total_repayment_estimate": 10416.00
},
"conditions": [],
"valid_until": "2026-02-11T00:00:00Z",
"created_at": "2026-01-11T10:00:00Z"
}
}
Credit Decision Types
| Decision | Description | Action |
|---|---|---|
approved | Fully approved | Proceed with order |
approved_conditions | Approved with conditions | Review conditions |
partially_approved | Lower amount approved | Consider reduced amount |
manual_review | Requires manual review | Contact support |
denied | Credit denied | Suggest alternative products |
Get Credit History
GET /credit-risk/history
Retrieve customer's credit assessment history.
history = client.credit_risk.history(
customer_id="cust_abc123",
page=1,
limit=20
)
Response
{
"data": [
{
"assessment_id": "assess_122",
"date": "2025-12-15",
"score": 715,
"decision": "approved",
"amount_requested": 5000.00,
"amount_approved": 5000.00
},
{
"assessment_id": "assess_121",
"date": "2025-11-01",
"score": 710,
"decision": "approved",
"amount_requested": 15000.00,
"amount_approved": 10000.00
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 12
}
}
Credit Improvement Recommendations
GET /credit-risk/recommendations
Get recommendations for improving creditworthiness.
recommendations = client.credit_risk.recommendations(
customer_id="cust_abc123"
)
Response
{
"data": {
"customer_id": "cust_abc123",
"current_score": 620,
"target_score": 700,
"timeline_months": 6,
"recommendations": [
{
"action": "complete_kyc",
"title": "Complete KYC Verification",
"impact": "+20 points",
"description": "Completing identity verification improves trust score"
},
{
"action": "link_bank_account",
"title": "Link Bank Account",
"impact": "+30 points",
"description": "Connect a verified bank account for payment history"
},
{
"action": "make_timely_payments",
"title": "Make Timely Payments",
"impact": "+40 points",
"description": "6 months of on-time payments significantly improves score"
},
{
"action": "reduce_utilization",
"title": "Reduce Credit Utilization",
"impact": "+25 points",
"description": "Keep utilization below 30% of available credit"
}
]
}
}
Webhook Events
| Event | Description |
|---|---|
credit.approved | Credit assessment approved |
credit.denied | Credit assessment denied |
credit.updated | Credit score updated |
credit.limit_reached | Credit limit threshold reached |
AI Credit Model
The credit scoring system uses a multi-model AI approach:
graph TD
A[Customer Data] --> B[Payment History Model]
A --> C[Behavioral Analysis Model]
A --> D[Financial Ratio Model]
A --> E[External Data Model]
B --> F[Ensemble Scoring]
C --> F
D --> F
E --> F
F --> G[Final Credit Score]
G --> H[Risk Classification]
H --> I[Credit Limit Recommendation]
Data Sources
- Internal Data: Payment history, subscription behavior, order patterns
- External Credit Bureaus: Traditional credit data (with consent)
- Bank Account Analysis: Transaction patterns, cash flow
- Alternative Data: Company financials, industry risk factors
Error Codes
| Code | Description |
|---|---|
CUSTOMER_NOT_FOUND | Customer ID not found |
ASSESSMENT_NOT_FOUND | Assessment ID not found |
INSUFFICIENT_DATA | Not enough data for scoring |
EXTERNAL_SERVICE_ERROR | Credit bureau unavailable |