Consumer Loans (`/api/v1/loans`)

Endpoints for creating, managing, extracting, and predicting risk for Consumer Loan Applications.

All endpoints require authentication via X-API-Key. Certain endpoints also require credit consumption.

1. Create Loan

Save a new consumer loan application.

Method: POST
Endpoint: /api/v1/loans
Authentication: Required

Request Body

Parameter	Type	Description
`age`	`Integer`	Applicant age
`income`	`Number`	Annual income
`loanAmount`	`Number`	Requested loan amount
`creditScore`	`Integer`	Credit score
`monthlyExpenses`	`Number`	Total monthly expenses
`numberOfCreditLines`	`Integer`	Number of open credit lines
`interestRate`	`Number`	Interest rate
`loanTerm`	`Integer`	Loan term in months
`dtiRatio`	`Number`	Debt-to-income ratio
`education`	`String`	Education level
`employmentType`	`String`	Employment type
`maritalStatus`	`String`	Marital status
`hasMortgage`	`Boolean`	Whether applicant has a mortgage
`hasDependents`	`Boolean`	Whether applicant has dependents
`loanPurpose`	`String`	Purpose of the loan
`hasCoSigner`	`Boolean`	Whether there is a co-signer
`businessRevenue`	`Number`	Business revenue (optional)
`applicationDate`	`String`	Application date (optional)
`actionTaken`	`String`	Action taken (optional)
`creditType`	`String`	Credit type (optional)
`creditPurpose`	`String`	Credit purpose (optional)
`pricingInfo`	`String`	Pricing info (optional)
`censusTract`	`String`	Census tract (optional)
`probabilityOfDefault`	`Number`	Pre-calculated PD (optional)
`notes`	`String`	Underwriter notes (optional)

Response (201 Created)

{
  "id": "uuid",
  "age": 35,
  "income": 85000.00,
  "loanAmount": 50000.00,
  "creditScore": 720,
  "monthlyExpenses": 2000.00,
  "numberOfCreditLines": 8,
  "interestRate": 5.50,
  "loanTerm": 36,
  "dtiRatio": 12.50,
  "education": "Bachelor",
  "employmentType": "Full-time",
  "maritalStatus": "Married",
  "hasMortgage": true,
  "hasDependents": false,
  "loanPurpose": "Home Improvement",
  "hasCoSigner": false,
  "businessRevenue": null,
  "applicationDate": null,
  "actionTaken": null,
  "creditType": null,
  "creditPurpose": null,
  "pricingInfo": null,
  "censusTract": null,
  "probabilityOfDefault": null,
  "notes": null,
  "status": "PENDING",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "userId": "uuid",
  "user": {
    "id": "uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "orgId": "uuid-or-null"
  }
}

2. Create Loan for Org User

Organisation owners can create a loan on behalf of a member.

Method: POST
Endpoint: /api/v1/loans/org-user
Authentication: Required (OWNER role)

Request Body

Same fields as Create Loan plus:

Parameter	Type	Description
`targetUserId`	`String`	Required. UUID of the organisation member

3. Get Loan by ID

Retrieve a specific loan.

Method: GET
Endpoint: /api/v1/loans/:id

Response

{
  "id": "uuid",
  "loanAmount": 50000.00,
  "status": "PENDING",
  ...all_loan_fields,
  "user": { "name": "John Doe", "email": "john@example.com" }
}

4. Update Loan

Update a loan's fields and/or status.

Method: PUT
Endpoint: /api/v1/loans/:id

Request Body

Same fields as Create Loan, plus:

Parameter	Type	Description
`status`	`String`	`PENDING`, `APPROVED`, or `REJECTED`

5. Delete Loan

Delete a loan.

Method: DELETE
Endpoint: /api/v1/loans/:id

Response

{ "message": "Loan deleted successfully" }

6. Predict Risk (Consumer Loan)

Execute the risk prediction algorithm on a consumer loan based on JSON input. Consumes credits (LOAN_PREDICTION).

Method: POST
Endpoint: /api/v1/loans/predict
Credits: 1 per call

Request Body

{
  "Age": 35,
  "Income": 85000,
  "LoanAmount": 15000,
  "CreditScore": 720,
  "MonthsEmployed": 24,
  "NumCreditLines": 8,
  "InterestRate": 10.5,
  "LoanTerm": 36,
  "DTIRatio": 12.5,
  "Education": "Bachelor",
  "EmploymentType": "Full-time",
  "MaritalStatus": "Married",
  "HasMortgage": "Yes",
  "HasDependents": "No",
  "LoanPurpose": "home_improvement",
  "HasCoSigner": "No",
  "Name": "John Doe",
  "Address": "123 Main St, Anytown, USA"
}

cURL
JavaScript

curl -X POST https://api.riskinmind.ai/api/v1/loans/predict \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Age": 35,
    "Income": 85000,
    "LoanAmount": 15000,
    "CreditScore": 720,
    "MonthsEmployed": 24,
    "NumCreditLines": 8,
    "InterestRate": 10.5,
    "LoanTerm": 36,
    "DTIRatio": 12.5,
    "Education": "Bachelor",
    "EmploymentType": "Full-time",
    "MaritalStatus": "Married",
    "HasMortgage": "Yes",
    "HasDependents": "No",
    "LoanPurpose": "home_improvement",
    "HasCoSigner": "No",
    "Name": "John Doe",
    "Address": "123 Main St"
  }'

const response = await fetch('https://api.riskinmind.ai/api/v1/loans/predict', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    Age: 35, Income: 85000, LoanAmount: 15000, CreditScore: 720,
    MonthsEmployed: 24, NumCreditLines: 8, InterestRate: 10.5,
    LoanTerm: 36, DTIRatio: 12.5, Education: "Bachelor",
    EmploymentType: "Full-time", MaritalStatus: "Married",
    HasMortgage: "Yes", HasDependents: "No",
    LoanPurpose: "home_improvement", HasCoSigner: "No",
    Name: "John Doe", Address: "123 Main St"
  })
});
const data = await response.json();

Response

Content-Type: application/json

{
  "probability": 0.85,
  "rejection_probability": 0.15
}

7. Generate Reports (Consumer & Commercial)

Trigger report generation based on the loan's data and return a PDF binary stream. Consumes credits (LOAN_REPORT_GEN).

The report PDF supports multiple languages via the optional language parameter (see the request body table below). language defaults to en when omitted or unrecognized, so existing integrations that don't send it are unaffected.

Consumer Report

Method: POST
Endpoint: /api/v1/loans/report/consumer

Commercial Report

Method: POST
Endpoint: /api/v1/loans/report/commercial

Request Body

Parameter	Type	Description
`name`	`String`	Borrower name
`Age`	`Number`	Applicant age
`Income`	`Number`	Annual income
`LoanAmount`	`Number`	Loan amount
`CreditScore`	`Number`	Credit score
`MonthsEmployed`	`Number`	Months employed
`NumCreditLines`	`Number`	Number of credit lines
`InterestRate`	`Number`	Interest rate
`LoanTerm`	`Number`	Loan term (months)
`LoanPurpose`	`String`	Purpose of the loan
`DTIRatio`	`Number`	Debt-to-income ratio
`PostLoanApprovalDTIRatio`	`Number`	Post-loan DTI ratio
`Education`	`String`	Education level
`EmploymentType`	`String`	Employment type
`MaritalStatus`	`String`	Marital status
`HasDependents`	`Boolean`	Has dependents
`NumDependents`	`Number`	Number of dependents
`HasCoSigner`	`Boolean`	Has co-signer
`UnderwriterNotes`	`String`	Underwriter notes
`HasMortgage`	`Boolean`	Has mortgage
`MonthlyMortgage`	`Number`	Monthly mortgage payment
`MonthlyPropertyTaxes`	`Number`	Monthly property taxes
`MonthlyInsurance`	`Number`	Monthly insurance
`MonthlyHOA`	`Number`	Monthly HOA fees
`MonthlyAlimonyChildSupport`	`Number`	Monthly alimony/child support
`MonthlyStudentLoan`	`Number`	Monthly student loan payment
`OtherMonthlyDebt`	`Number`	Other monthly debt
`MonthlyCreditCard`	`Number`	Monthly credit card expenses
`MonthlyAutoLoan`	`Number`	Monthly auto loan payment
`probability_of_default`	`Number`	Probability of default
`language`	`String`	(optional) Report PDF language. One of `en`, `de`, `es`, `fr`, `hi`, `ne`, `zh`. Defaults to `en` if omitted or unrecognized.

Response

Content-Type: application/pdf
Returns: Binary PDF stream (consumer_loan_report.pdf or commercial_loan_report.pdf), localized to the requested language (English by default)

cURL
JavaScript

curl -X POST https://api.riskinmind.ai/api/v1/loans/report/consumer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John Doe", "Age": 35, "Income": 85000, "LoanAmount": 15000 }' \
  --output consumer_loan_report.pdf

const response = await fetch('https://api.riskinmind.ai/api/v1/loans/report/consumer', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: "John Doe", Age: 35, Income: 85000, LoanAmount: 15000,
    language: "es" // optional — defaults to "en"
  })
});
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = 'consumer_loan_report.pdf';
link.click();

8. CECL Prediction Engine

Calculate Current Expected Credit Losses (CECL) using the RiskInMind financial math engine. Consumes credits (CECL_ANALYSIS).

Method: POST
Endpoint: /api/v1/loans/cecl

Request Body (Array of loan exposures)

[
  {
    "loanId": "loan_123",
    "exposureAtDefault": 50000,
    "probabilityOfDefault": 0.02,
    "lossGivenDefault": 0.45
  }
]

cURL
JavaScript

curl -X POST https://api.riskinmind.ai/api/v1/loans/cecl \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "loanId": "loan_123",
      "exposureAtDefault": 50000,
      "probabilityOfDefault": 0.02,
      "lossGivenDefault": 0.45
    }
  ]'

const response = await fetch('https://api.riskinmind.ai/api/v1/loans/cecl', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify([{
    loanId: "loan_123",
    exposureAtDefault: 50000,
    probabilityOfDefault: 0.02,
    lossGivenDefault: 0.45
  }])
});
const data = await response.json();

Response

{
  "totalExpectedLoss": 450.00,
  "breakdown": []
}

9. 1003 Loan Application Generation

Generate a standardized Uniform Residential Loan Application (Form 1003) PDF. Consumes credits (LOAN_1003_GEN).

Method: POST
Endpoint: /api/v1/loans/1003
Authentication: Required (OWNER role in organisation)

Request Body

Parameter	Type	Description
`userId`	`String`	UUID of the borrower
`orgId`	`String`	UUID of the organisation
`borrower`	`Object`	Borrower details (name, address, SSN, marital status, DOB, citizenship, dependents, etc.)
`employment`	`Object`	Employment details (employer name, phone, address, income breakdown)
`loan_property`	`Object`	Loan property details (amount, purpose, address)
`declarations`	`Object`	Bankruptcy, judgments, citizenship, occupancy declarations
`loan_originator`	`Object`	Originator details (org info, NMLSR ID, license, contact)

{
  "userId": "user-uuid",
  "orgId": "org-uuid",
  "borrower": {
    "first_name": "John",
    "last_name": "Doe",
    "marital_status": "Married",
    "dependents": 2,
    "ssn": "XXX-XX-XXXX",
    "dob": "1990-01-15",
    "citizenship_status": "US Citizen",
    "current_address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip_code": "12345"
    }
  },
  "employment": {
    "employer_name": "Acme Corp",
    "phone": "555-0100",
    "address": { "street": "456 Oak Ave", "city": "Anytown", "state": "CA", "zip_code": "12345" },
    "base_income": 70000,
    "overtime_income": 5000,
    "bonus_income": 10000,
    "commission_income": 0
  },
  "loan_property": {
    "loan_amount": 350000,
    "loan_purpose": "Purchase",
    "property_address": {
      "street": "789 Pine Rd",
      "city": "Othertown",
      "state": "CA",
      "zip_code": "54321"
    }
  },
  "declarations": {
    "bankruptcy": false,
    "outstanding_judgments": false,
    "citizen_of_us": true,
    "intend_to_occupy": true
  },
  "loan_originator": {
    "organization_name": "RiskInMind Lending",
    "originator_name": "Jane Agent",
    "originator_nmlsr_id": "NMLS-12345",
    "originator_email": "jane@riskinmind.com"
  }
}

Response

Content-Type: application/pdf
Returns: Binary PDF stream of the completed 1003 form.

10. Get Extracted Loan Data

Retrieve aggregated extracted data from uploaded documents (bank statements, tax returns, pay stubs, etc.).

Method: GET
Endpoint: /api/v1/loans/extracted-data
Query Param: userId (optional — org owners can query their members)

Response

{
  "success": true,
  "data": {
    "income": 85000,
    "employer_name": "Acme Corp",
    "bank_routing": "021000021",
    ...
  },
  "values": {
    "income": "85000.00",
    "employer_name": "Acme Corp",
    ...
  }
}

11. Public Loan Data (Shareable)

Retrieve a loan's basic info and prediction without authentication — for shareable reports.

Method: POST
Endpoint: /api/v1/loans/public/data
Authentication: None

Request Body

{ "id": "loan-uuid" }

Response

{
  "loan": {
    "id": "uuid",
    "loanAmount": 50000,
    ...
    "user": { "name": "John Doe", "email": "john@example.com" }
  },
  "prediction": {
    "probability_of_default": 0.05,
    "probability_of_default_percent": "5.0%"
  }
}

12. Email Public Loan Report

Share a loan report via email without authentication.

Method: POST
Endpoint: /api/v1/loans/public/email-report
Authentication: None

Request Body

{
  "email": "recipient@example.com",
  "borrower_name": "John Doe",
  "loan_id": "loan-uuid",
  "report_url": "https://riskinmind.com/share/..."
}

Response

{
  "success": true,
  "message": "Report shared successfully via email"
}

1. Create Loan​

Request Body​

Response (201 Created)​

2. Create Loan for Org User​

Request Body​

3. Get Loan by ID​

Response​

4. Update Loan​

Request Body​

5. Delete Loan​

Response​

6. Predict Risk (Consumer Loan)​

Request Body​

Response​

7. Generate Reports (Consumer & Commercial)​

Consumer Report​

Commercial Report​

Request Body​

Response​

8. CECL Prediction Engine​

Request Body (Array of loan exposures)​

Response​

9. 1003 Loan Application Generation​

Request Body​

Response​

10. Get Extracted Loan Data​

Response​

11. Public Loan Data (Shareable)​

Request Body​

Response​

12. Email Public Loan Report​

Request Body​

Response​

1. Create Loan

Request Body

Response (201 Created)

2. Create Loan for Org User

Request Body

3. Get Loan by ID

Response

4. Update Loan

Request Body

5. Delete Loan

Response

6. Predict Risk (Consumer Loan)

Request Body

Response

7. Generate Reports (Consumer & Commercial)

Consumer Report

Commercial Report

Request Body

Response

8. CECL Prediction Engine

Request Body (Array of loan exposures)

Response

9. 1003 Loan Application Generation

Request Body

Response

10. Get Extracted Loan Data

Response

11. Public Loan Data (Shareable)

Request Body

Response

12. Email Public Loan Report

Request Body

Response