Borrower Repayment Score

This document describes the API for calculating a repayment score for a borrower. The score is based on a borrower's historical payment behavior, including payment amounts, payment times, and delinquencies.

Base URL

https://score.cladfy.com/v1

API Endpoint:

POST /repayment_score/

Request Headers:

Content-Type: application/json
X-API-Key: Your unique API. Please email us at [email protected] for an API Key.

Request Body:

The request body contains the borrower's payment history and configuration for score calculation. It should be JSON with the properties below.

  • paymentStartDate: The start date of the scoring period (YYYY-MM-DD format).
  • paymentEndDate: The end date of the scoring period (YYYY-MM-DD format). If not provided, the current date is used.
  • expectedPaymentDay: The expected day of the month for payments (integer between 1 and 31).
  • expectedPaymentAmount: The expected monthly payment amount (integer).
  • payments: A list of Payment dictionaries containing details for each single payment. Properties include:
    • date: The date of the payment (YYYY-MM-DD format).
    • amount: The amount paid (integer).
  • reference (Optional): A reference string associated with the borrower.
  • scoreBeforeStartDate (Optional): A boolean flag indicating whether to include a score for the period before the payment start date.
  • client_id: A unique client identifier you send to our APIs is returned to you for data syncing.

Example Request Body:

{
    "paymentStartDate": "2023-01-01",
    "paymentEndDate": "2023-12-31",
    "expectedPaymentDay": 5,
    "expectedPaymentAmount": 1000,
    "payments": [
        {"date": "2023-01-01", "amount": 1200},
        {"date": "2023-02-05", "amount": 1000},
        {"date": "2023-03-05", "amount": 1000},
        {"date": "2023-04-01", "amount": 1500},
        {"date": "2023-05-25", "amount": 600},
    ],
    "reference": "Your Reference Here",
    "scoreBeforeStartDate": True,
    "client_id": "12345"  # Replace with your actual client ID
}

Response:

The response will be a JSON object following the Score data type specification: A typed dictionary containing the calculated repayment score and detailed results. Properties include:

  • overallScore: The overall repayment score (integer between 0 and 1).
  • paidStreak: The number of consecutive months with on-time or early payments (integer).
  • overDueStreak: The number of consecutive months with overdue payments (integer).
  • scoredMonths: A list of ScoredMonth dictionaries for each month within the scoring period.
    • status: The payment status for the month (from PaymentStatus).
    • score: The score assigned to the month (integer between 0 and 1).
    • dueDate: The due date for the payment (YYYY-MM-DD format).
    • balance: The outstanding balance at the end of the month (integer).
  • expectedPaymentAmount: The expected monthly payment amount (integer).
  • balance: The outstanding balance at the end of the scoring period (integer).
  • error (Optional): A ScoreError enum value if an error occurred.

Example Response:

{'client_id': '12345',
 'repayment_score': 
 {'balance': -7000, 
  'expectedPaymentAmount': 1000, 
  'overDueStreak': 7, 
  'overallScore': 0.53, 
  'paidStreak': 5, 
  'scoredMonths': [
      {'balance': 200, 'dueDate': '23-01-05', 'score': 1.04, 'status': 'OVERPAID'
      },
      {'balance': 200, 'dueDate': '23-02-05', 'score': 1.0, 'status': 'OVERPAID'
      },
      {'balance': 200, 'dueDate': '23-03-05', 'score': 1.0, 'status': 'OVERPAID'
      },
      {'balance': 700, 'dueDate': '23-04-05', 'score': 1.05, 'status': 'OVERPAID'
      },
      {'balance': 0, 'dueDate': '23-05-05', 'score': 1, 'status': 'PAID'
      },
      {'balance': -1000, 'dueDate': '23-06-05', 'score': 0.25, 'status': 'OVERDUE'
      },
      {'balance': -2000, 'dueDate': '23-07-05', 'score': 0.21, 'status': 'OVERDUE'
      },
      {'balance': -3000, 'dueDate': '23-08-05', 'score': 0.19, 'status': 'OVERDUE'
      },
      {'balance': -4000, 'dueDate': '23-09-05', 'score': 0.17, 'status': 'OVERDUE'
      },
      {'balance': -5000, 'dueDate': '23-10-05', 'score': 0.15, 'status': 'OVERDUE'
      },
      {'balance': -6000, 'dueDate': '23-11-05', 'score': 0.14, 'status': 'OVERDUE'
      },
      {'balance': -7000, 'dueDate': '23-12-05', 'score': 0.12, 'status': 'OVERDUE'
      }
    ]
  }
}

Error Handling:

401 Unauthorized: If the API key is invalid.
400 Bad Request: If the request body is not valid JSON or missing required fields.
500 Internal Server Error: If an internal server error occurs during score calculation. The response will include an error message.

Additional Notes:

  • The specific attributes supported by the scorecard and their formats might vary depending on the implementation. Please refer to the detailed scorecard documentation provided by Cladfy via email.
  • The API logs the call with the provided API key and service name ("repayment_score").

Python Test Example:

This test example demonstrates sending a POST request to the API endpoint with borrower data containing payment details for a loan. The response will include a repayment score considering the late payment history.

import requests
import json  # Import the json library

# Define the API endpoint URL
url = "http://score.cladfy.com/v1/repayment_score/"

# Set the request headers
headers = {
    "Content-Type": "application/json",
    "X-API-Key": YOUR_API_KEY
}
# Prepare the JSON data for the borrower (Example with late payments)
data = {
    "paymentStartDate": "2023-01-01",
    "paymentEndDate": "2023-12-31",
    "expectedPaymentDay": 5,
    "expectedPaymentAmount": 1000,
    "payments": [
        {"date": "2023-01-01", "amount": 1200},#ontime payment
        {"date": "2023-02-05", "amount": 1000},
        {"date": "2023-03-05", "amount": 1000},
        {"date": "2023-04-01", "amount": 1500},
        {"date": "2023-05-25", "amount": 600},#Late payment
    ],
    "reference": "Your Reference Here",
    "scoreBeforeStartDate": True,
    "client_id": "12345"  # Replace with your actual client ID
}
# Convert the dictionary to a JSON string using json.dumps
json_data = json.dumps(data)

# Send the POST request with the JSON-formatted string
response = requests.post(url, headers=headers, json=json_data)
# Check for successful response
if response.status_code == 200:
    # Get the JSON response data
    data = response.json()
    print("Repayment Score:", data)  # Access the score from the response data
else:
    print("Error:", response.status_code, response.text)


cURL Test Example:

This curl command demonstrates sending a POST request to the API endpoint with borrower data in JSON format.

curl -X POST http://score.cladfy.com/v1/repayment_score/ -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"client_id": "12345", "paymentStartDate": "2023-01-01", "paymentEndDate": "2023-12-31", "expectedPaymentDay": 5, "expectedPaymentAmount": 1000, "payments": [{"date": "2023-01-05", "amount": 1000}, {"date": "2023-02-05", "amount": 1000}], "reference": "Your Reference Here", "scoreBeforeStartDate": true}' -v

Important Note: http://score.cladfy.com/v1/repayment_score/ is the actual URL of the repayment score API and you should replace "YOUR_API_KEY" with your actual API key before running the script.