Client Deposit Score

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.