# N-Score API Documentation

## Overview

The N-Score API provides comprehensive scoring information for users, including various sub-scores (personal, household, KYC, PAN, financial) and the overall N-Score. This API aggregates scoring data from multiple sources to provide a complete view of a user's creditworthiness and profile completion status.

**Base URL**: `https://core.nanope.ai`

**API Version**: v1

---

## Endpoint

### Get User Score by User ID

Retrieve comprehensive scoring information for a specific user, including all sub-scores and the final N-Score.

**Endpoint**: `/api/score/{user_id}`

**Method**: `GET`

**Full URL**: `https://core.nanope.ai/api/score/{user_id}`

**Path Parameter**: `user_id` (string, required) - The unique identifier for the user (MongoDB ObjectId format)

---

## Request

### Path Parameters

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `user_id` | string | Yes | User's unique identifier (MongoDB ObjectId) | `692e6db1cc7c914386725a39` |

### Example Request

```bash
GET https://core.nanope.ai/api/score/692e6db1cc7c914386725a39
```

```javascript
// JavaScript/Fetch example
const userId = '692e6db1cc7c914386725a39';
fetch(`https://core.nanope.ai/api/score/${userId}`)
  .then(response => response.json())
  .then(data => {
    console.log('N-Score:', data.total_score);
    console.log('Summary:', data.summary);
  })
  .catch(error => console.error('Error:', error));
```

```python
# Python example
import requests

user_id = "692e6db1cc7c914386725a39"
url = f"https://core.nanope.ai/api/score/{user_id}"
response = requests.get(url)
data = response.json()
print(f"N-Score: {data['total_score']}")
```

---

## Response

### Success Response

**Status Code**: `200 OK`

**Content-Type**: `application/json`

**Response Body**:
```json
{
  "data": [
    {
      "Avg Score": "",
      "Category": "",
      "Completion%": "",
      "Cumulative Score": 0,
      "Date": "",
      "Day Score": 0,
      "Score_15": 0,
      "Status": "personal score"
    },
    {
      "Avg Score": "",
      "Category": "",
      "Completion%": "",
      "Cumulative Score": 0,
      "Date": "",
      "Day Score": 0,
      "Score_15": 0,
      "Status": "household score"
    },
    {
      "Avg Score": "",
      "Category": "",
      "Completion%": "",
      "Cumulative Score": 0,
      "Date": "",
      "Day Score": 0,
      "Score_15": 0,
      "Status": "kyc score"
    },
    {
      "Avg Score": "",
      "Category": "",
      "Completion%": "",
      "Cumulative Score": 0,
      "Date": "2026-01-15",
      "Day Score": 0,
      "Score_15": 0,
      "Status": "pan score"
    },
    {
      "Avg Score": "",
      "Category": "",
      "Completion%": "",
      "Cumulative Score": 0,
      "Date": "",
      "Day Score": 0,
      "Score_15": 0,
      "Status": "financial score"
    }
  ],
  "financial_score": {
    "date": "",
    "message": "Financial data not found for user 692e6db1cc7c914386725a39",
    "score": 0,
    "success": false,
    "user_id": "692e6db1cc7c914386725a39"
  },
  "household_score": {
    "date": "",
    "message": "User 692e6db1cc7c914386725a39 not found in USER_PERSONAL collection",
    "score": 0,
    "success": false,
    "user_id": "692e6db1cc7c914386725a39"
  },
  "kyc_score": {
    "date": "",
    "max_score": 5,
    "message": "User 692e6db1cc7c914386725a39 not found",
    "score": 0,
    "success": 0,
    "user_id": "692e6db1cc7c914386725a39"
  },
  "loan_journey": {
    "daily_view": [],
    "error": "No payment records found",
    "loan_details": {},
    "loan_ids": []
  },
  "pan_score": {
    "date": "15 Jan 2026",
    "max_score": 5,
    "message": "User finance data not found",
    "score": 0,
    "success": 0,
    "user_id": "692e6db1cc7c914386725a39"
  },
  "personal_score": {
    "date": "",
    "message": "User 692e6db1cc7c914386725a39 not found",
    "score": 0,
    "success": false,
    "user_id": "692e6db1cc7c914386725a39"
  },
  "score": {
    "NG_SCORE": "0",
    "days": 0,
    "pd": "",
    "score": 0,
    "success": true
  },
  "start_date": "2025-09-01",
  "summary": {
    "final_cumulative_score": 0,
    "financial_score": 0,
    "household_score": 0,
    "kyc_score": 0,
    "loan_journey_score": 0,
    "pan_score": 0,
    "personal_score": 0,
    "total_loans": 0
  },
  "total_records": 5,
  "total_score": 0,
  "user_id": "692e6db1cc7c914386725a39"
}
```

---

## Response Fields

### Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | The user ID used in the request |
| `total_score` | number | **The N-Score value** - This is the primary score used for loan eligibility |
| `total_records` | number | Total number of score records in the `data` array |
| `start_date` | string | Start date for score calculation period (format: "YYYY-MM-DD") |
| `data` | array | Array of score detail objects for different score types |
| `summary` | object | Summary object containing aggregated scores |
| `score` | object | Overall score object with NG_SCORE |
| `personal_score` | object | Personal score details |
| `household_score` | object | Household score details |
| `kyc_score` | object | KYC (Know Your Customer) score details |
| `pan_score` | object | PAN (Permanent Account Number) score details |
| `financial_score` | object | Financial score details |
| `loan_journey` | object | Loan journey and payment history details |

### Data Array Objects

Each object in the `data` array represents a score type with the following structure:

| Field | Type | Description |
|-------|------|-------------|
| `Status` | string | Type of score (e.g., "personal score", "household score", "kyc score", "pan score", "financial score") |
| `Cumulative Score` | number | Cumulative score for this category |
| `Day Score` | number | Daily score value |
| `Score_15` | number | Score calculated over 15 days |
| `Avg Score` | string | Average score (may be empty) |
| `Category` | string | Category classification (may be empty) |
| `Completion%` | string | Completion percentage (may be empty) |
| `Date` | string | Date associated with the score (format: "YYYY-MM-DD" or empty) |

### Summary Object

| Field | Type | Description |
|-------|------|-------------|
| `final_cumulative_score` | number | Final cumulative score across all categories |
| `personal_score` | number | Aggregated personal score |
| `household_score` | number | Aggregated household score |
| `kyc_score` | number | Aggregated KYC score |
| `pan_score` | number | Aggregated PAN score |
| `financial_score` | number | Aggregated financial score |
| `loan_journey_score` | number | Score based on loan journey and payment history |
| `total_loans` | number | Total number of loans for the user |

### Score Object (NG_SCORE)

| Field | Type | Description |
|-------|------|-------------|
| `NG_SCORE` | string | NG Score value (as string) |
| `score` | number | Numeric score value |
| `days` | number | Number of days calculated |
| `pd` | string | Additional score data (may be empty) |
| `success` | boolean | Whether the score calculation was successful |

### Personal Score Object

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | User ID |
| `score` | number | Personal score value |
| `date` | string | Date of score calculation (may be empty) |
| `success` | boolean | Whether the score was successfully calculated |
| `message` | string | Status message (e.g., "User not found") |

### Household Score Object

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | User ID |
| `score` | number | Household score value |
| `date` | string | Date of score calculation (may be empty) |
| `success` | boolean | Whether the score was successfully calculated |
| `message` | string | Status message (e.g., "User not found in USER_PERSONAL collection") |

### KYC Score Object

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | User ID |
| `score` | number | KYC score value |
| `max_score` | number | Maximum possible KYC score |
| `date` | string | Date of score calculation (may be empty) |
| `success` | number | Success status (0 = false, 1 = true) |
| `message` | string | Status message |

### PAN Score Object

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | User ID |
| `score` | number | PAN score value |
| `max_score` | number | Maximum possible PAN score |
| `date` | string | Date of score calculation (format: "DD MMM YYYY" or empty) |
| `success` | number | Success status (0 = false, 1 = true) |
| `message` | string | Status message |

### Financial Score Object

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | User ID |
| `score` | number | Financial score value |
| `date` | string | Date of score calculation (may be empty) |
| `success` | boolean | Whether the score was successfully calculated |
| `message` | string | Status message (e.g., "Financial data not found") |

### Loan Journey Object

| Field | Type | Description |
|-------|------|-------------|
| `loan_ids` | array | Array of loan IDs associated with the user |
| `loan_details` | object | Detailed loan information (may be empty) |
| `daily_view` | array | Array of daily payment/view records |
| `error` | string | Error message if no payment records found (may be empty) |

---

## Important Notes

### N-Score Extraction

**The `total_score` field contains the N-Score value** that should be used for:
- Loan eligibility determination
- Product matching (as used in FPL Products API)
- Creditworthiness assessment

Example:
```javascript
const nScore = response.total_score; // This is the N-Score
```

### Score Status Indicators

- **Success indicators vary by score type**:
  - `personal_score`, `household_score`, `financial_score`: Use boolean `success` field
  - `kyc_score`, `pan_score`: Use numeric `success` field (0 = false, 1 = true)

- **Empty or zero scores** may indicate:
  - User data not found
  - Incomplete profile
  - No historical data available

### Date Formats

- `start_date`: "YYYY-MM-DD" format (e.g., "2025-09-01")
- `data[].Date`: "YYYY-MM-DD" format or empty string
- `pan_score.date`: "DD MMM YYYY" format (e.g., "15 Jan 2026") or empty string
- Other date fields: May be empty strings if not available

---

## Error Responses

### 400 Bad Request

Invalid user ID format.

**Response**:
```json
{
  "error": "Invalid user ID format",
  "code": 400
}
```

### 404 Not Found

User not found.

**Response**:
```json
{
  "error": "User not found",
  "code": 404
}
```

### 500 Internal Server Error

Server error occurred while processing the request.

**Response**:
```json
{
  "error": "Internal server error",
  "code": 500
}
```

---

## Usage Examples

### Example 1: Get N-Score for a User

```bash
curl -X GET "https://core.nanope.ai/api/score/692e6db1cc7c914386725a39"
```

### Example 2: JavaScript/TypeScript

```typescript
interface ScoreDetail {
  "Avg Score": string;
  "Category": string;
  "Completion%": string;
  "Cumulative Score": number;
  "Date": string;
  "Day Score": number;
  "Score_15": number;
  "Status": string;
}

interface SubScore {
  user_id: string;
  score: number;
  date: string;
  success: boolean | number;
  message: string;
  max_score?: number;
}

interface LoanJourney {
  loan_ids: string[];
  loan_details: Record<string, any>;
  daily_view: any[];
  error?: string;
}

interface ScoreSummary {
  final_cumulative_score: number;
  financial_score: number;
  household_score: number;
  kyc_score: number;
  loan_journey_score: number;
  pan_score: number;
  personal_score: number;
  total_loans: number;
}

interface NScoreResponse {
  user_id: string;
  total_score: number; // This is the N-Score
  total_records: number;
  start_date: string;
  data: ScoreDetail[];
  summary: ScoreSummary;
  score: {
    NG_SCORE: string;
    days: number;
    pd: string;
    score: number;
    success: boolean;
  };
  personal_score: SubScore;
  household_score: SubScore;
  kyc_score: SubScore & { max_score: number };
  pan_score: SubScore & { max_score: number };
  financial_score: SubScore;
  loan_journey: LoanJourney;
}

async function getNScore(userId: string): Promise<number> {
  const response = await fetch(
    `https://core.nanope.ai/api/score/${userId}`
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data: NScoreResponse = await response.json();
  
  // Extract N-Score
  return data.total_score;
}

// Usage
getNScore('692e6db1cc7c914386725a39')
  .then(nScore => {
    console.log(`User N-Score: ${nScore}`);
  })
  .catch(error => console.error('Error:', error));
```

### Example 3: Python

```python
import requests
from typing import Dict, Any, Optional

def get_n_score(user_id: str) -> Optional[float]:
    """
    Get N-Score for a user.
    
    Args:
        user_id: User's unique identifier
        
    Returns:
        N-Score value (total_score) or None if error
    """
    url = f"https://core.nanope.ai/api/score/{user_id}"
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()
        
        # Extract N-Score
        return data.get('total_score')
    except requests.exceptions.RequestException as e:
        print(f"Error fetching N-Score: {e}")
        return None

def get_comprehensive_score(user_id: str) -> Dict[str, Any]:
    """
    Get comprehensive score information for a user.
    
    Args:
        user_id: User's unique identifier
        
    Returns:
        Complete score data dictionary
    """
    url = f"https://core.nanope.ai/api/score/{user_id}"
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching score data: {e}")
        return {}

# Usage
user_id = "692e6db1cc7c914386725a39"

# Get just the N-Score
n_score = get_n_score(user_id)
print(f"N-Score: {n_score}")

# Get comprehensive score data
score_data = get_comprehensive_score(user_id)
if score_data:
    print(f"\nUser ID: {score_data.get('user_id')}")
    print(f"N-Score: {score_data.get('total_score')}")
    print(f"\nSummary:")
    summary = score_data.get('summary', {})
    print(f"  Personal Score: {summary.get('personal_score')}")
    print(f"  Household Score: {summary.get('household_score')}")
    print(f"  KYC Score: {summary.get('kyc_score')}")
    print(f"  PAN Score: {summary.get('pan_score')}")
    print(f"  Financial Score: {summary.get('financial_score')}")
    print(f"  Loan Journey Score: {summary.get('loan_journey_score')}")
    print(f"  Total Loans: {summary.get('total_loans')}")
```

### Example 4: Using N-Score with FPL Products API

```javascript
// Get N-Score first
async function getLoanProducts(userId) {
  // Step 1: Get N-Score
  const scoreResponse = await fetch(
    `https://core.nanope.ai/api/score/${userId}`
  );
  const scoreData = await scoreResponse.json();
  const nScore = scoreData.total_score;
  
  // Step 2: Get available loan products using N-Score
  const productsResponse = await fetch(
    `https://fpl.nanope.ai/api/lms/products/userid?n_score=${nScore}`
  );
  const productsData = await productsResponse.json();
  
  return {
    nScore: nScore,
    products: productsData.products,
    totalProducts: productsData.total
  };
}

// Usage
getLoanProducts('692e6db1cc7c914386725a39')
  .then(result => {
    console.log(`N-Score: ${result.nScore}`);
    console.log(`Available Products: ${result.totalProducts}`);
    result.products.forEach(product => {
      console.log(`- ${product.productName}: ${product.principalAmount}`);
    });
  });
```

---

## Integration Notes

### N-Score Usage

The `total_score` field is the primary value used for:
1. **Loan Eligibility**: Determining which loan products a user qualifies for
2. **Product Matching**: Used as input to the FPL Products API (`n_score` parameter)
3. **Credit Assessment**: Overall creditworthiness indicator

### Score Calculation

The N-Score is calculated based on multiple factors:
- Personal score
- Household score
- KYC completion score
- PAN verification score
- Financial data score
- Loan journey/payment history score

### Data Availability

- Scores may be `0` if user data is not found or incomplete
- Check `success` fields in sub-score objects to determine data availability
- Empty strings in date fields indicate missing data

### Caching Considerations

- N-Score may change over time as user data is updated
- Consider caching with appropriate TTL based on your use case
- Refresh scores before making loan eligibility decisions

### Error Handling

- Always check if `total_score` exists and is a valid number
- Handle cases where sub-scores may have errors
- Validate user_id format before making requests

---

## Related APIs

- **FPL Products API**: Use the `total_score` (N-Score) value as the `n_score` parameter
  - Endpoint: `https://fpl.nanope.ai/api/lms/products/userid?n_score={total_score}`
  - See `FPL_PRODUCTS_API.md` for details

---

## Changelog

### Version 1.0
- Initial API documentation
- Documented `/api/score/{user_id}` endpoint
- Added comprehensive field descriptions
- Included usage examples and integration notes
- Documented N-Score extraction from `total_score` field

---

## Support

For issues or questions regarding this API:
- Contact the Core service team
- Check related API documentation for integration details

---

**Last Updated**: January 2026