POST /v1/reports — submit a renter risk report

The POST /v1/reports endpoint lets you submit a rental history report for a renter. RentFAX uses the payment, asset condition, and contract compliance data you provide to calculate a weighted risk score and assign an eligibility status. The report is immediately stored and linked to your organization.

All requests must include a valid API key in the Authorization header. See Authentication for details.

Endpoint

POST https://api.rentfax.io/v1/reports

Request body

renterEmail

string

required

The renter’s email address. Used to match against existing renter profiles in the RentFAX network.

renterName

string

required

The renter’s full name.

industryType

string

required

The industry vertical for this report (for example, "residential", "commercial", "equipment"). This value is stored as-is and used for portfolio filtering.

renterPhone

string

The renter’s phone number. Optional, stored for contact reference.

contractId

string

Your internal contract or lease identifier. Useful for cross-referencing reports with your own records.

paymentCompliance

string

How the renter met their payment obligations. Carries a 40% weight in the risk score calculation.

Value	Score
`"Paid As Agreed"`	1000
`"Paid Late"`	400
`"Not Paid"`	0

Defaults to "Paid As Agreed" (score 1000) if omitted.

assetCondition

string

The condition of the rented asset at the end of the rental period. Carries a 30% weight in the risk score calculation.

Value	Score
`"No Damage"`	1000
`"Cosmetic Wear"`	750
`"Repairable Damage"`	400
`"Structural Damage"`	150
`"Total Loss"`	0

Defaults to "No Damage" (score 1000) if omitted.

contractCompliance

string

How well the renter adhered to the terms of the contract. Carries a 20% weight in the risk score calculation.

Value	Score
`"Compliant"`	1000
`"Minor Violation"`	650
`"Early Termination"`	350
`"Major Breach"`	100

Defaults to "Compliant" (score 1000) if omitted.

incidents

array

An array of incident identifiers or objects to associate with this report. Incidents are logged separately via POST /v1/incidents/submit and can be referenced here.

totalCharged

number

The total amount billed to the renter over the rental period, in the smallest currency unit (for example, cents).

totalPaid

number

The total amount the renter actually paid, in the smallest currency unit.

outstandingBalance

number

The amount still owed by the renter at the time of reporting, in the smallest currency unit.

Risk score calculation

RentFAX computes a composite risk score on a 0–1000 scale using a weighted formula:

riskScore =
  (paymentComplianceScore × 0.40) +
  (assetConditionScore   × 0.30) +
  (contractComplianceScore × 0.20) +
  (700 × 0.10)

The final term (700 × 0.10 = 70) is a fixed network baseline contribution applied to every report.

Eligibility thresholds

Risk score	Eligibility status
≥ 750	`Eligible`
≥ 500	`Eligible With Conditions`
≥ 250	`Elevated Risk`
< 250	`Do Not Rent`

If you omit all three compliance fields, RentFAX defaults each score to 1000, producing a maximum risk score of 1000 and an Eligible status. Always supply the compliance fields that are relevant to your rental type for accurate scoring.

Response

A successful request returns HTTP 200 with the following fields.

boolean

required

true when the report was created successfully.

reportId

string

required

The unique report ID. Use this to reference the report in subsequent API calls.

recordId

string

required

A human-readable record identifier in the format RB-XXXXX (for example, RB-47291). This is the ID shown in the RentFAX dashboard and suitable for display to end users.

riskScore

number

required

The computed risk score (0–1000) for this renter based on the compliance data you submitted.

Examples

curl --request POST \
  --url https://api.rentfax.io/v1/reports \
  --header 'Authorization: Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "renterEmail": "jane.doe@example.com",
    "renterName": "Jane Doe",
    "industryType": "residential",
    "renterPhone": "+15555550100",
    "contractId": "LEASE-2024-00192",
    "paymentCompliance": "Paid Late",
    "assetCondition": "Cosmetic Wear",
    "contractCompliance": "Compliant",
    "incidents": [],
    "totalCharged": 1800000,
    "totalPaid": 1800000,
    "outstandingBalance": 0
  }'

const response = await fetch('https://api.rentfax.io/v1/reports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    renterEmail: 'jane.doe@example.com',
    renterName: 'Jane Doe',
    industryType: 'residential',
    renterPhone: '+15555550100',
    contractId: 'LEASE-2024-00192',
    paymentCompliance: 'Paid Late',
    assetCondition: 'Cosmetic Wear',
    contractCompliance: 'Compliant',
    incidents: [],
    totalCharged: 1800000,
    totalPaid: 1800000,
    outstandingBalance: 0,
  }),
});

const data = await response.json();
console.log(data.riskScore); // 655

import requests

response = requests.post(
    "https://api.rentfax.io/v1/reports",
    headers={
        "Authorization": "Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "renterEmail": "jane.doe@example.com",
        "renterName": "Jane Doe",
        "industryType": "residential",
        "renterPhone": "+15555550100",
        "contractId": "LEASE-2024-00192",
        "paymentCompliance": "Paid Late",
        "assetCondition": "Cosmetic Wear",
        "contractCompliance": "Compliant",
        "incidents": [],
        "totalCharged": 1800000,
        "totalPaid": 1800000,
        "outstandingBalance": 0,
    },
)

print(response.json())

Example response

200

{
  "ok": true,
  "reportId": "3qFzW8mNkLpT2vXcYdAe",
  "recordId": "RB-47291",
  "riskScore": 655
}

Score breakdown for this example

Factor	Value	Score	Weight	Contribution
Payment compliance	`"Paid Late"`	400	40%	160
Asset condition	`"Cosmetic Wear"`	750	30%	225
Contract compliance	`"Compliant"`	1000	20%	200
Network baseline	—	700	10%	70
Total				655

Error responses

400

{
  "error": "renterEmail and renterName required"
}

401

{
  "error": "Unauthorized"
}

Overview

Renters

Reports & Incidents

Webhooks

POST /v1/reports — submit a renter risk report

Endpoint

Request body

Risk score calculation

Eligibility thresholds

Response

Examples

Example response

Error responses

​Endpoint

​Request body

​Risk score calculation

​Eligibility thresholds

​Response

​Examples

​Example response

​Error responses

Endpoint

Request body

Risk score calculation

Eligibility thresholds

Response

Examples

Example response

Error responses