> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rentfax.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Submit a full rental history report for a renter. RentFAX computes a risk score and recommendation and adds the report to the network immediately.

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.

<Note>
  All requests must include a valid API key. See [Authentication](/api-reference/authentication) for details.
</Note>

## Endpoint

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

## Request body

<ParamField body="renter_email" type="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.
</ParamField>

<ParamField body="renter_name" type="string">
  The renter's full name. Required if `renter_email` is not provided.
</ParamField>

<ParamField body="renter_phone" type="string">
  The renter's phone number. Optional, stored for reference.
</ParamField>

<ParamField body="rental_period" type="string">
  A description or date range for the rental period (for example, `"2024-01-01 to 2024-06-30"`). Optional, stored for reference.
</ParamField>

<ParamField body="total_charged" type="number">
  Total amount billed to the renter over the rental period, in the smallest currency unit (for example, cents).
</ParamField>

<ParamField body="total_paid" type="number">
  Total amount the renter actually paid, in the smallest currency unit.
</ParamField>

<ParamField body="outstanding_balance" type="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.
</ParamField>

<ParamField body="incidents" type="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.
</ParamField>

<ParamField body="damage" type="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.
</ParamField>

<ParamField body="recommendation" type="string">
  Override the computed recommendation level. If omitted, RentFAX assigns one based on the score: `approved` (≥ 800), `conditional` (≥ 600), `denied` (≥ 400), or `blacklist` (\< 400).
</ParamField>

<ParamField body="notes" type="string">
  A free-text narrative about the rental. Optional, stored with the report for reference.
</ParamField>

## 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.

<ResponseField name="ok" type="boolean" required>
  `true` when the report was created successfully.
</ResponseField>

<ResponseField name="report_id" type="string" required>
  The unique report ID. Use this to reference the report in subsequent operations.
</ResponseField>

<ResponseField name="score" type="number" required>
  The computed risk score (100–1000) for this renter based on the data you submitted.
</ResponseField>

<ResponseField name="recommendation" type="string" required>
  The recommendation level: `approved`, `conditional`, `denied`, or `blacklist`.
</ResponseField>

<ResponseField name="message" type="string" required>
  A confirmation message. Always `"Report filed and added to the RentFAX network."` on success.
</ResponseField>

<ResponseField name="filed_at" type="string" required>
  ISO 8601 timestamp of when the report was created.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  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."
    }'
  ```

  ```javascript Node.js theme={null}
  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"
  ```
</CodeGroup>

### Example response

```json 201 theme={null}
{
  "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

```json 400 theme={null}
{
  "ok": false,
  "error": "renter_email or renter_name required"
}
```

```json 401 theme={null}
{
  "ok": false,
  "error": "Missing API key."
}
```

<Tip>
  Use `POST /v1/renter/report` when you have raw financial data and incident lists. Use [`POST /v1/reports`](/api-reference/reports/submit) when you want to classify compliance using the standard label system (`"Paid As Agreed"`, `"No Damage"`, etc.).
</Tip>