This document describes the API for calculating a demographic score for a borrower. The score is based on a predefined set of rules in a JSON format scorecard.
Base URL
https://score.cladfy.com/v1
API Endpoint:
POST /demographic_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 a JSON object containing the borrower's demographic data. The expected attributes and their formats should be specified in the API documentation provided by the service provider.
client_id
: A unique client identifier you send to our APIs is returned to you for data syncing.
Example Request Body:
{
"client_id": "12345",
"age": 30,
"location": "city",
"customer_tier": "tier_2",
"marital_status": "married",
# ... other borrower data
}
Response:
The response will be a JSON object with the following properties:
score
: The calculated demographic score (integer value between 0 and 130)
max_score
: The maximum possible score for the scorecard (130 in this example)
missing_attributes
: A list of attributes in the scorecard that were missing in the borrower data (empty list if none are missing)
extra_attributes
: A list of attributes present in the borrower data that were not defined in the scorecard (empty list if none are present)
Example Response:
{
"client_id": "12345",
"score": overall_demographic_score (Integer),
"max_score": 120 (Integer),
"missing_attributes": ["attribute1", "attribute2"] (List of Strings, optional),
"extra_attributes": ["attributeX", "attributeY"] (List of Strings, optional)
}
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 ("demographic_score").
Python Test Example:
This test example demonstrates sending a POST request to the API endpoint with client data. The response will include a demographic score.
import requests
import json # Import the json library
# Define the API endpoint URL
url = "https://score.cladfy.com/v1/demographic_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
data = {
"client_id": "12345",
"location": "city",
"customer_tier": "tier_2",
}
# 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("Demographic Score:", data["score"]) # 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 data in JSON format.
curl -X POST https://score.cladfy.com/v1/demographic_score/ -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"client_id": "12345", "location": "city"}'
Important Note: https://score.cladfy.com/v1/demographic_score/
is the actual URL of your demographic score API and you should replace "YOUR_API_KEY" with your actual API key before running the script.