Skip to content

api.md

Latest commit

 

History

History
255 lines (233 loc) · 5.5 KB

api.md

File metadata and controls

255 lines (233 loc) · 5.5 KB
Raw

Fin-Trust - API Documentation

This document describes all API endpoints exposed by the Fin-Trust backend.

🔒 Base Configurations

  • Development URL: http://localhost:5000/api
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <JWT_TOKEN> (Required for all protected routes)

🔑 Authentication Endpoints (/api/auth)

1. User Registration

Creates a new unverified user account. Sends a verification OTP to the user's email.

  • Method: POST
  • Endpoint: /auth/register
  • Auth Required: No
  • Request Body: 
    {
  "name": "Asha Rao",
  "email": "asharao@example.com",
  "password": "SecurePassword123!",
  "role": "borrower"
}
  • Success Response (201 Created): 
    {
  "success": true,
  "message": "Registration successful. Please check your email for a verification code.",
  "user": {
    "name": "Asha Rao",
    "email": "asharao@example.com",
    "role": "borrower",
    "isActive": true,
    "isVerified": false,
    "_id": "6a6a3e1f6c4695c3a0a44ccc",
    "createdAt": "2026-07-29T17:53:35.451Z"
  }
}

2. Verify Email OTP

Verifies the user's email using the sent 6-digit OTP code.

  • Method: POST
  • Endpoint: /auth/verify-email
  • Auth Required: No
  • Request Body: 
    {
  "email": "asharao@example.com",
  "otp": "579525"
}
  • Success Response (200 OK): 
    {
  "success": true,
  "message": "Email verified successfully. You can now log in."
}

3. Login

Validates credentials and issues a JWT token.

  • Method: POST
  • Endpoint: /auth/login
  • Auth Required: No
  • Request Body: 
    {
  "email": "asharao@example.com",
  "password": "SecurePassword123!"
}
  • Success Response (200 OK): 
    {
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "6a6a3e1f6c4695c3a0a44ccc",
    "name": "Asha Rao",
    "email": "asharao@example.com",
    "role": "borrower",
    "isActive": true,
    "isVerified": true
  }
}

📋 Borrower Endpoints (/api/borrowers)

1. Create/Submit Loan Application

Submits loan requirements and coordinates for trust analysis.

  • Method: POST
  • Endpoint: /borrowers
  • Auth Required: Yes (borrower role only)
  • Request Body: 
    {
  "amount": 50000,
  "duration": 12,
  "purpose": "Home renovation",
  "income": 45000,
  "employmentStatus": "salaried",
  "city": "Mumbai",
  "latitude": 19.0760,
  "longitude": 72.8777
}
  • Success Response (201 Created): 
    {
  "success": true,
  "borrower": {
    "user": "6a6a3e1f6c4695c3a0a44ccc",
    "amount": 50000,
    "duration": 12,
    "purpose": "Home renovation",
    "income": 45000,
    "employmentStatus": "salaried",
    "city": "Mumbai",
    "latitude": 19.0760,
    "longitude": 72.8777,
    "trustScore": 65,
    "isApproved": true
  }
}

2. Upload KYC Documents

Uploads files (Aadhaar, PAN, Bank Statement) for OCR processing and name verification.

  • Method: POST
  • Endpoint: /borrowers/upload-kyc
  • Auth Required: Yes (borrower role only)
  • Request Format: multipart/form-data
  • Parameters:
    • file: (File binary)
    • type: aadhaar | pan | bank
  • Success Response (200 OK): 
    {
  "success": true,
  "message": "KYC file uploaded and verified successfully",
  "extractedName": "ASHA RAO",
  "scoreChange": 15
}

💼 Lender Endpoints (/api/lenders)

1. Setup Lender Profile

Configures preferences and limits.

  • Method: POST
  • Endpoint: /lenders
  • Auth Required: Yes (lender role only)
  • Request Body: 
    {
  "minAmount": 10000,
  "maxAmount": 100000,
  "minTrustScore": 60,
  "preferredDuration": 12,
  "city": "Mumbai",
  "latitude": 19.0760,
  "longitude": 72.8777
}
  • Success Response (201 Created): 
    {
  "success": true,
  "lender": {
    "user": "6a6a3e1f6c4695c3a0a44ddd",
    "minAmount": 10000,
    "maxAmount": 100000,
    "minTrustScore": 60,
    "preferredDuration": 12,
    "city": "Mumbai"
  }
}

🤝 Match Endpoints (/api/matches)

1. Accept Profile Match

  • Method: PUT
  • Endpoint: /matches/:id/accept
  • Auth Required: Yes (Either role)
  • Request Body: 
    {
  "agreedToDisclaimer": true
}
  • Success Response (200 OK): 
    {
  "success": true,
  "message": "Match accepted successfully"
}

2. View Match Contact Details

Returns the private contact details once both parties have accepted.

  • Method: GET
  • Endpoint: /matches/:id/contact
  • Auth Required: Yes (Either matching profile owner)
  • Success Response (200 OK): 
    {
  "success": true,
  "contact": {
    "name": "Nikhitha J Gadad",
    "email": "nikhithagadad@gmail.com",
    "phone": "+919876543210"
  }
}

🛡️ Admin Endpoints (/api/admin)

1. Get Platform Statistics

Returns high-level user and matching statistics.

  • Method: GET
  • Endpoint: /admin/stats
  • Auth Required: Yes (admin role only)
  • Success Response (200 OK): 
    {
  "success": true,
  "stats": {
    "totalUsers": 24,
    "totalBorrowers": 12,
    "totalLenders": 8,
    "totalMatches": 45,
    "acceptedMatches": 14,
    "rejectedMatches": 5,
    "pendingApplications": 3
  }
}