> ## 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/search — search for renters

> Search the RentFAX network by member ID, email, phone, or name. Returns matching renter records with eligibility status, rent score, and fraud indicators.

The `/v1/search` endpoint lets you find renters in the RentFAX network before committing to a full screening check. Send one identifier in the request body and you'll receive a list of matching records, each with an eligibility classification and rent score. This is useful for autocomplete lookups, pre-fill flows, and confirming that the right renter is selected before calling `/v1/renter/check` for the full report.

<Note>
  Only one identifier is used per request. When multiple fields are provided, the API applies this priority order: `memberId → email → phone → name`.
</Note>

## Endpoint

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

## Authentication

Include your API key in one of two ways:

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

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

## Request body

Send a JSON object with at least one of the following fields.

<ParamField body="memberId" type="string">
  The renter's RentFAX member ID. Normalized to uppercase. Returns at most 1 result.
</ParamField>

<ParamField body="email" type="string">
  The renter's email address. Normalized to lowercase. Returns at most 5 results.
</ParamField>

<ParamField body="phone" type="string">
  The renter's phone number. Non-digit characters are stripped before matching. Returns at most 5 results.
</ParamField>

<ParamField body="name" type="string">
  The renter's full name. Matched using a prefix search on the normalized name index. Returns at most 10 results.
</ParamField>

## Response fields

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

<ResponseField name="count" type="number" required>
  Number of records returned.
</ResponseField>

<ResponseField name="results" type="object[]" required>
  Array of matching renter records.

  <Expandable title="results item properties">
    <ResponseField name="renterId" type="string">
      The renter's internal RentFAX ID. Pass this to `/v1/renter/score` for a detailed score breakdown.
    </ResponseField>

    <ResponseField name="memberId" type="string | null">
      The renter's network member ID, or `null` if not assigned.
    </ResponseField>

    <ResponseField name="fullName" type="string | null">
      The renter's full name as recorded in the network.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The renter's email address.
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      `true` if the renter's identity has been verified by RentFAX.
    </ResponseField>

    <ResponseField name="rentScore" type="number">
      The renter's composite rent score, 0 – 1000.
    </ResponseField>

    <ResponseField name="eligibility" type="string">
      Eligibility classification derived from `rentScore`.

      | Value                      | Score range |
      | -------------------------- | ----------- |
      | `ELIGIBLE`                 | 750 – 1000  |
      | `ELIGIBLE_WITH_CONDITIONS` | 500 – 749   |
      | `ELEVATED_RISK`            | 250 – 499   |
      | `DO_NOT_RENT`              | 0 – 249     |
    </ResponseField>

    <ResponseField name="fraudReported" type="boolean">
      `true` if a fraud report has been filed against this renter in the network.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```bash cURL theme={null}
curl --request POST \
  --url "https://api.rentfax.io/v1/search" \
  --header "x-api-key: rfx_live_your_api_key_here" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "jane.doe@example.com"
  }'
```

### Response

```json theme={null}
{
  "ok": true,
  "count": 1,
  "results": [
    {
      "renterId": "rtr_7f3a92c1d8e04b6f",
      "memberId": "MBR-00291847",
      "fullName": "Jane Doe",
      "email": "jane.doe@example.com",
      "verified": true,
      "rentScore": 847,
      "eligibility": "ELIGIBLE",
      "fraudReported": false
    }
  ]
}
```

### Response — no matches

```json theme={null}
{
  "ok": true,
  "count": 0,
  "results": []
}
```

<Tip>
  Use the `renterId` from a search result to call `/v1/renter/score` for the full component breakdown, or `/v1/renter/check` with `member_id` for a complete screening report.
</Tip>