POST /v1/renter/report — file a renter report

The POST /v1/renter/report endpoint lets you file a complete rental history report for a renter directly from your system. Unlike POST /v1/reports which uses compliance category labels, this endpoint accepts raw financial figures, incident lists, and damage arrays to compute a risk score. The report is stored in the RentFAX network and affects the renter’s profile immediately.

All requests must include a valid API key. See Authentication for details.

Endpoint

POST https://api.rentfax.io/v1/renter/report

Request body

renter_email

string

The renter’s email address. Used to match and update an existing renter profile. At least one of renter_email or renter_name is required.

renter_name

string

The renter’s full name. Required if renter_email is not provided.

renter_phone

string

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

rental_period

string

A description or date range for the rental period (for example, "2024-01-01 to 2024-06-30"). Optional, stored for reference.

total_charged

number

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

total_paid

number

Total amount the renter actually paid, in the smallest currency unit.

outstanding_balance

number

Amount still owed by the renter at the time of reporting, in the smallest currency unit. An outstanding balance greater than zero reduces the computed risk score by 200 points.

incidents

array

An array of incident type strings associated with this rental (for example, ["late_payment", "noise_complaint"]). Each incident reduces the risk score by 100 points.

damage

array

An array of damage descriptions for this rental (for example, ["scratched bumper", "broken window"]). Any damage entries reduce the risk score by 150 points.

recommendation

string

Override the computed recommendation level. If omitted, RentFAX assigns one based on the score: approved (≥ 800), conditional (≥ 600), denied (≥ 400), or blacklist (< 400).

notes

string

A free-text narrative about the rental. Optional, stored with the report for reference.

Risk score calculation

RentFAX computes the score starting at 1000 and subtracting penalties:

score = max(100, 1000
  − (outstanding_balance > 0 ? 200 : 0)
  − (incidents.length × 100)
  − (damage.length > 0 ? 150 : 0))

The resulting score drives the recommendation level:

Score range	Recommendation
≥ 800	`approved`
≥ 600	`conditional`
≥ 400	`denied`
< 400	`blacklist`

Response

A successful request returns HTTP 201 with the following fields.

boolean

required

true when the report was created successfully.

report_id

string

required

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

score

number

required

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

recommendation

string

required

The recommendation level: approved, conditional, denied, or blacklist.

message

string

required

A confirmation message. Always "Report filed and added to the RentFAX network." on success.

filed_at

string

required

ISO 8601 timestamp of when the report was created.

Example

curl --request POST \
  --url https://api.rentfax.io/v1/renter/report \
  --header 'Authorization: Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "renter_email": "jane.doe@example.com",
    "renter_name": "Jane Doe",
    "renter_phone": "+15555550100",
    "rental_period": "2024-01-01 to 2024-06-30",
    "total_charged": 1200000,
    "total_paid": 1200000,
    "outstanding_balance": 0,
    "incidents": [],
    "damage": [],
    "notes": "Tenant vacated on time. Unit left in good condition."
  }'

const response = await fetch('https://api.rentfax.io/v1/renter/report', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    renter_email: 'jane.doe@example.com',
    renter_name: 'Jane Doe',
    total_charged: 1200000,
    total_paid: 1200000,
    outstanding_balance: 0,
    incidents: [],
    damage: [],
  }),
});

const data = await response.json();
console.log(data.score);           // 1000
console.log(data.recommendation);  // "approved"

Example response

201

{
  "ok": true,
  "report_id": "7aKpM3nQrLwTxVyZ",
  "score": 1000,
  "recommendation": "approved",
  "message": "Report filed and added to the RentFAX network.",
  "filed_at": "2026-05-04T10:30:00.000Z"
}

Error responses

400

{
  "ok": false,
  "error": "renter_email or renter_name required"
}

401

{
  "ok": false,
  "error": "Missing API key."
}

Use POST /v1/renter/report when you have raw financial data and incident lists. Use POST /v1/reports when you want to classify compliance using the standard label system ("Paid As Agreed", "No Damage", etc.).

Overview

Renters

Reports & Incidents

Webhooks

POST /v1/renter/report — file a renter report

Endpoint

Request body

Risk score calculation

Response

Example

Example response

Error responses

​Endpoint

​Request body

​Risk score calculation

​Response

​Example

​Example response

​Error responses

Endpoint

Request body

Risk score calculation

Response

Example

Example response

Error responses