> ## 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/reports — submit a renter risk report

> Submit a rental history report for a renter. RentFAX calculates a risk score and eligibility status from the compliance data you provide.

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.

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

## Endpoint

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

## Request body

<ParamField body="renterEmail" type="string" required>
  The renter's email address. Used to match against existing renter profiles in the RentFAX network.
</ParamField>

<ParamField body="renterName" type="string" required>
  The renter's full name.
</ParamField>

<ParamField body="industryType" type="string" required>
  The industry vertical for this report (for example, `"residential"`, `"commercial"`, `"equipment"`). This value is stored as-is and used for portfolio filtering.
</ParamField>

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

<ParamField body="contractId" type="string">
  Your internal contract or lease identifier. Useful for cross-referencing reports with your own records.
</ParamField>

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

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

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

<ParamField body="incidents" type="array">
  An array of incident identifiers or objects to associate with this report. Incidents are logged separately via [`POST /v1/incidents/submit`](/api-reference/incidents/submit) and can be referenced here.
</ParamField>

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

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

<ParamField body="outstandingBalance" type="number">
  The amount still owed by the renter at the time of reporting, in the smallest currency unit.
</ParamField>

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

<Tip>
  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.
</Tip>

## Response

A successful request returns HTTP `200` with the following fields.

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

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

<ResponseField name="recordId" type="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.
</ResponseField>

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

## Examples

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

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

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "ok": true,
  "reportId": "3qFzW8mNkLpT2vXcYdAe",
  "recordId": "RB-47291",
  "riskScore": 655
}
```

<Accordion title="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**      |
</Accordion>

### Error responses

```json 400 theme={null}
{
  "error": "renterEmail and renterName required"
}
```

```json 401 theme={null}
{
  "error": "Unauthorized"
}
```