Tenant Scoring Quickstart#

Generate risk scores, cash flow analysis, and income verification for tenants. Scoring uses data from Verification Reports to produce actionable risk assessments with regulatory-compliant adverse action codes.

Step 1: Create a Score Request#

After a Verification Report is complete, request tenant scoring:

curl https://api.casapay.com/v1/score_requests \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_report": "vr_9z8y7x6w5v",
    "score_types": ["tenant_score", "cash_flow_score", "credit_score"]
  }'

{
  "id": "sr_abc123def456",
  "object": "score_request",
  "verification_report": "vr_9z8y7x6w5v",
  "score_types": ["tenant_score", "cash_flow_score", "credit_score"],
  "status": "processing",
  "created": 1706140800
}

Step 2: Retrieve the Score Report#

When processing completes, retrieve the full score report:

curl https://api.casapay.com/v1/score_reports/scrpt_xyz789 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

{
  "id": "scrpt_xyz789",
  "object": "score_report",
  "score_request": "sr_abc123def456",
  "scores": [
    {
      "score_type": "tenant_score",
      "value": 82,
      "score_version": "v2.1",
      "risk_indicator": "low_risk",
      "adverse_action_codes": []
    },
    {
      "score_type": "cash_flow_score",
      "value": 78,
      "score_version": "v1.3",
      "risk_indicator": "low_risk",
      "adverse_action_codes": []
    },
    {
      "score_type": "credit_score",
      "value": 65,
      "score_version": "v1.0",
      "risk_indicator": "medium_risk",
      "adverse_action_codes": [
        { "code": "AC-201", "description": "Limited credit history length" }
      ]
    }
  ],
  "attributes": [
    { "name": "monthly_income", "node": "INCOME", "value": 600000 },
    { "name": "monthly_expenses", "node": "EXPENSES", "value": 420000 },
    { "name": "net_monthly_cash_flow", "node": "ASSETS", "value": 180000 },
    { "name": "rent_to_income_ratio", "node": "INCOME", "value": 0.28 }
  ]
}

Step 3: Apply Scoring Logic#

Use scores and attributes to automate tenant approval:

const report = await casapay.scoreReports.retrieve('scrpt_xyz789');

const tenantScore = report.scores.find(s => s.score_type === 'tenant_score');
const rentToIncome = report.attributes.find(a => a.name === 'rent_to_income_ratio');

if (tenantScore.value >= 70 && rentToIncome.value <= 0.35) {
  // Auto-approve
  await approveApplication(report);
} else if (tenantScore.risk_indicator === 'high_risk') {
  // Auto-decline with adverse action codes
  await declineApplication(report, tenantScore.adverse_action_codes);
} else {
  // Manual review
  await flagForReview(report);
}

Adverse action codes are required by fair lending regulations when declining a tenant based on credit data. Always include these codes in denial notices.