Client Deposit Score

This document describes the API for calculating a deposit score of a depositor. The score is based on the depositor's historical deposit behavior, including deposit consistency, deposit amounts, timeliness of deposits, and the presence of partial deposits.

Base URL

https://score.cladfy.com/v1

API Endpoint:

POST /deposit_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 should be JSON following the ScoreInput data type specification below.

  • startDate (str): The start date of the scoring period in ISO 8601 format (YYYY-MM-DD).
  • endDate (str): The end date of the scoring period in ISO 8601 format (YYYY-MM-DD).
  • expectedDepositDay (str): The expected day of the month for deposits (e.g., "5").
  • expectedDepositAmount (int): The expected amount of each deposit.
  • deposits (List[{}]): A list of dictionaries containing deposit details. Each dictionary should have the following keys:
    • date (str): The date of the deposit in ISO 8601 format (YYYY-MM-DD).
    • amount (int): The amount deposited.
  • client_id: A unique client identifier you send to our APIs is returned to you for data syncing.

Example Request Body:

{
  "client_id": "12345",
    "startDate": "2023-10-09",
    "endDate": "2024-01-08",
    "expectedDepositDay": "5",
    "expectedDepositAmount": 1500,
    "deposits": [
        {"date": "2023-11-05", "amount": 1600},
        {"date": "2023-12-05", "amount": 1500},
        {"date": "2024-01-05", "amount": 1550},
        {"date": "2024-02-05", "amount": 1550}
    ]
}

Response:

The API returns a dictionary with the following keys:

  • Overall Deposit Score (float): A value between 0 and 1 representing the overall deposit score.
  • Individually Scored Months (Dict[str, float]): A dictionary where keys are month strings (YYYY-MM) and values are individual deposit scores for each month (between 0 and 1).
  • Longest On-time Deposit Streak (int): The longest streak of consecutive on-time deposits within the scoring period.
  • Longest Late Deposit Streak (int): The longest streak of consecutive late deposits within the scoring period (currently initialized to 0).
  • Partial Deposit Count: This is the number of all partial deposits
{"client_id": "12345",
 'Individually Scored Months': 
 {'2023-11': 0.9, '2023-12': 1.0, 
  '2024-01': 1.1, '2024-02': 1.2
  }, 
 'Longest Late Deposit Streak': 0, 
 'Longest On-time Deposit Streak': 4, 
 'Overall Deposit Score': 0.43,
 "Partial Deposit Count": 2
}

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 ("deposit_score").

Python Test Example:

This test example demonstrates sending a POST request to the API endpoint with client data containing money deposits to an account. The response will include a deposit score considering the late payment history. 

import requests
import json  # Import the json library

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

# Set the request headers
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"  # Replace with your actual API key
}

# Prepare the JSON data for the borrower (Example with some on-time deposits)
data = {
  "client_id": "12345",
    "startDate": "2023-10-09",
    "endDate": "2024-01-08",
    "expectedDepositDay": "5",
    "expectedDepositAmount": 1500,
    "deposits": [
        {"date": "2023-11-05", "amount": 1600},  # Deposit on expected day
        {"date": "2023-12-10", "amount": 1500},  # Late deposit
        {"date": "2024-01-05", "amount": 1550},  # Deposit on expected day
        {"date": "2024-02-05", "amount": 1550}  # Deposit on expected day
    ]
}

# 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("Deposit Score with some Late Deposits:", 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 client deposit data in JSON format.

curl -X POST https://score.cladfy.com/v1/deposit_score/ -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"client_id": "12345", "startDate": "2023-10-09", "endDate": "2024-03-08", "expectedDepositDay": "16", "expectedDepositAmount": 2100, "deposits": [{"date": "2023-11-16", "amount": 1500},{"date": "2023-12-26", "amount": 2100}, {"date": "2024-01-06", "amount": 100}, {"date": "2024-02-16", "amount": 2100}]}'

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