# Estimate research hours

> For AI agents: a documentation index is available at [https://heirpros.com/llms.txt](https://heirpros.com/llms.txt). This page is also available as markdown at [https://heirpros.com/developers/estimate-hours.md](https://heirpros.com/developers/estimate-hours.md).

`POST https://heirpros.com/api/v1/hours` with a JSON body. Requires an [API key](https://heirpros.com/developers/authentication/).

## Formula

Estimated hours = 1.5 + known heirs + estimated unknown heirs. The optional case details are checked but do not change the hours in v1.

## Fields

| Field | Type | Values |
| --- | --- | --- |
| `known_heirs` | integer, required | Total number of known family members. 1 to 100. |
| `unknown_heirs` | integer, required | Estimated number of unknown family members. 1 to 25. |
| `estate_type` | optional | testate, intestate or n/a |
| `search_purpose` | optional | notice, distribution or n/a |
| `has_identifying_info` | optional | yes or no |
| `last_contact_known` | optional | yes, no or unknown |
| `lifestyle_considerations` | optional | yes, no or unknown |
| `distribution_method` | optional | per stirpes, per capita or unsure |
| `immigration_or_emigration` | optional | yes or no |
| `has_additional_details` | optional | yes or no |

## Example request

```bash
curl -X POST https://heirpros.com/api/v1/hours \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"known_heirs": 3, "unknown_heirs": 2, "estate_type": "intestate"}'
```

## Example response (200)

```json
{
  "estimated_hours": 6.5,
  "total_heirs": 5,
  "known_heirs": 3,
  "unknown_heirs": 2,
  "case_details": { "estate_type": "intestate" },
  "method": "1.5 base hours plus 1 hour per known and estimated unknown heir.",
  "note": "This is an estimate. Final hours are confirmed by HeirPros before work starts."
}
```

## Response fields

| Field | Meaning |
| --- | --- |
| `estimated_hours` | The estimated research hours. |
| `total_heirs` | Known plus estimated unknown heirs. |
| `case_details` | The optional details you sent, normalized to lower case. |
| `method` | How the hours were worked out. |
| `note` | Reminder that HeirPros confirms final hours. |

Invalid input returns `422 validation_failed` and names each field. See [Errors](https://heirpros.com/developers/errors/).
