> ## 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/incidents/submit — report a renter incident

> Submit a discrete incident record for a renter. Incidents are factored into risk scoring when referenced in a rental history report.

The `POST /v1/incidents/submit` endpoint lets you record a specific incident associated with a renter — such as a late payment, property damage event, or lease violation. Each incident is stored under your organization and can be referenced in a full rental history report submitted via [`POST /v1/reports`](/api-reference/reports/submit).

<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/incidents/submit
```

## How incidents affect risk scores

Incidents submitted through this endpoint are discrete records stored in the RentFAX network. When you submit a rental history report via `POST /v1/reports`, you can include incident IDs in the `incidents` array field. The presence and type of linked incidents are considered as part of the overall renter risk profile.

<Tip>
  Log incidents as they occur rather than in bulk at the end of a lease. Accurate timestamps and detailed descriptions give the risk model better signal and help resolve disputes faster.
</Tip>

## Request body

<ParamField body="renterId" type="string" required>
  The identifier for the renter this incident is associated with. This should match the renter's record in your system or the RentFAX network.
</ParamField>

<ParamField body="industry" type="string" required>
  The industry vertical this incident belongs to (for example, `"residential"`, `"commercial"`, `"equipment"`). Must be consistent with the `industryType` used when filing reports for this renter.
</ParamField>

<ParamField body="type" type="string" required>
  A short category label for the incident. Examples: `"late_payment"`, `"property_damage"`, `"lease_violation"`, `"noise_complaint"`. This value is stored as-is; use a consistent taxonomy across your integration.
</ParamField>

<ParamField body="details" type="string" required>
  A plain-text description of the incident. Include relevant context such as the date it occurred, the severity, and any corrective action taken. This field is surfaced to reviewers and AI risk summaries.
</ParamField>

## Response

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

<ResponseField name="success" type="boolean" required>
  `true` when the incident was recorded successfully.
</ResponseField>

<ResponseField name="incidentId" type="string" required>
  The unique identifier for the created incident record. Store this value if you intend to reference the incident in a future `POST /v1/reports` request via the `incidents` array.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.rentfax.io/v1/incidents/submit \
    --header 'Authorization: Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "renterId": "renter_abc123",
      "industry": "residential",
      "type": "late_payment",
      "details": "Renter failed to pay the March 2024 installment on time. Payment was received 18 days after the due date following a formal notice. No prior late payment history."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.rentfax.io/v1/incidents/submit', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      renterId: 'renter_abc123',
      industry: 'residential',
      type: 'late_payment',
      details:
        'Renter failed to pay the March 2024 installment on time. Payment was received 18 days after the due date following a formal notice. No prior late payment history.',
    }),
  });

  const data = await response.json();
  console.log(data.incidentId); // "xK9mL2nPqRsTuVwX"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.rentfax.io/v1/incidents/submit",
      headers={
          "Authorization": "Bearer rfx_live_xxxxxxxxxxxxxxxxxxxx",
          "Content-Type": "application/json",
      },
      json={
          "renterId": "renter_abc123",
          "industry": "residential",
          "type": "late_payment",
          "details": (
              "Renter failed to pay the March 2024 installment on time. "
              "Payment was received 18 days after the due date following a "
              "formal notice. No prior late payment history."
          ),
      },
  )

  print(response.json())
  ```
</CodeGroup>

### Example response

```json 200 theme={null}
{
  "success": true,
  "incidentId": "xK9mL2nPqRsTuVwX"
}
```

### Error responses

```json 400 theme={null}
{
  "error": "Missing required fields: renterId, industry, type, details"
}
```

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