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

# GET /v1/renter/score — get composite risk score

> Retrieve a detailed, component-level risk score for a renter by their RentFAX ID. Includes payment history, asset condition, identity, and network standing.

The `/v1/renter/score` endpoint returns the full breakdown of a renter's composite risk score. While `/v1/renter/check` gives you a pass/review/deny recommendation, this endpoint gives you the underlying math: four weighted components that add up to a score out of 1000, plus the financial data that feeds those calculations. Use it when you need to explain a decision to a renter, build a custom scoring UI, or audit how a score changed over time.

## Endpoint

```
GET https://api.rentfax.io/v1/renter/score
```

## Authentication

Include your API key in one of two ways:

```
x-api-key: <your-api-key>
```

```
Authorization: Bearer <your-api-key>
```

## Query parameters

<ParamField query="renter_id" type="string" required>
  The internal RentFAX renter ID. You can obtain this from the `renterId` field in a `/v1/search` response, or from your own renter records.
</ParamField>

## Score components

The composite score is a weighted average of four components:

| Component           | Weight | What it measures                                          |
| ------------------- | ------ | --------------------------------------------------------- |
| `payment_history`   | 40%    | Proportion of reports with no outstanding balance         |
| `asset_condition`   | 30%    | Proportion of reports with no damage findings             |
| `identity_verified` | 20%    | Whether the renter has completed identity verification    |
| `network_standing`  | 10%    | Absence of outstanding unpaid balances across the network |

Each component score is on a 0 – 1000 scale. The composite is computed as:

```
composite = (payment_history × 0.40) + (asset_condition × 0.30)
          + (identity_verified × 0.20) + (network_standing × 0.10)
```

## Response fields

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

<ResponseField name="renter_id" type="string" required>
  The renter ID that was scored, echoed back for correlation.
</ResponseField>

<ResponseField name="composite_score" type="number" required>
  The weighted composite score, 0 – 1000.
</ResponseField>

<ResponseField name="score_max" type="number" required>
  Maximum possible score. Always `1000`.
</ResponseField>

<ResponseField name="components" type="object" required>
  Individual score components with their weights and qualitative labels.

  <Expandable title="components properties">
    <ResponseField name="payment_history" type="object">
      Measures how consistently the renter has settled balances. Weighted at 40%.

      <Expandable title="payment_history properties">
        <ResponseField name="score" type="number">
          Component score, 0 – 1000.
        </ResponseField>

        <ResponseField name="weight" type="string">
          Always `"40%"`.
        </ResponseField>

        <ResponseField name="label" type="string">
          Qualitative label: `"Excellent"`, `"Good"`, or `"Poor"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="asset_condition" type="object">
      Measures how often the renter returns assets without damage. Weighted at 30%.

      <Expandable title="asset_condition properties">
        <ResponseField name="score" type="number">
          Component score, 0 – 1000.
        </ResponseField>

        <ResponseField name="weight" type="string">
          Always `"30%"`.
        </ResponseField>

        <ResponseField name="label" type="string">
          Qualitative label: `"Excellent"`, `"Good"`, or `"Poor"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="identity_verified" type="object">
      Reflects whether the renter has completed RentFAX identity verification. Weighted at 20%.

      <Expandable title="identity_verified properties">
        <ResponseField name="score" type="number">
          `900` if the renter is verified, `600` if not.
        </ResponseField>

        <ResponseField name="weight" type="string">
          Always `"20%"`.
        </ResponseField>

        <ResponseField name="label" type="string">
          `"Verified"` or `"Unverified"`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="network_standing" type="object">
      Reflects the absence of outstanding balances across the network. Weighted at 10%.

      <Expandable title="network_standing properties">
        <ResponseField name="score" type="number">
          Component score, 0 – 1000. Decreases by 150 for each unpaid report, floored at 0.
        </ResponseField>

        <ResponseField name="weight" type="string">
          Always `"10%"`.
        </ResponseField>

        <ResponseField name="label" type="string">
          `"Good Standing"` or `"Has Outstanding Balances"`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="financials" type="object" required>
  Raw financial data from the renter's report history.

  <Expandable title="financials properties">
    <ResponseField name="total_reports" type="number">
      Total number of reports considered in this score calculation (up to the 20 most recent).
    </ResponseField>

    <ResponseField name="paid_in_full" type="number">
      Number of reports where the renter owed no outstanding balance.
    </ResponseField>

    <ResponseField name="outstanding_balances" type="number">
      Number of reports where the renter still has an unpaid amount.
    </ResponseField>

    <ResponseField name="total_owed" type="number">
      Sum of all outstanding balances across all reports, in cents.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="calculated_at" type="string" required>
  ISO 8601 timestamp of when this score was calculated.
</ResponseField>

## Example

```bash cURL theme={null}
curl --request GET \
  --url "https://api.rentfax.io/v1/renter/score?renter_id=rtr_7f3a92c1d8e04b6f" \
  --header "x-api-key: rfx_live_your_api_key_here"
```

### Response

```json theme={null}
{
  "ok": true,
  "renter_id": "rtr_7f3a92c1d8e04b6f",
  "composite_score": 847,
  "score_max": 1000,
  "components": {
    "payment_history": {
      "score": 909,
      "weight": "40%",
      "label": "Excellent"
    },
    "asset_condition": {
      "score": 833,
      "weight": "30%",
      "label": "Excellent"
    },
    "identity_verified": {
      "score": 900,
      "weight": "20%",
      "label": "Verified"
    },
    "network_standing": {
      "score": 700,
      "weight": "10%",
      "label": "Has Outstanding Balances"
    }
  },
  "financials": {
    "total_reports": 11,
    "paid_in_full": 10,
    "outstanding_balances": 1,
    "total_owed": 32500
  },
  "calculated_at": "2026-05-04T10:22:45.000Z"
}
```

<Tip>
  Scores are calculated on demand from the renter's most recent 20 reports. Call this endpoint again after new reports are filed to get an updated score.
</Tip>