Client Demographic Score

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:

JSON

{  
  "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:

JSON

{
  "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.

Python

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

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.