---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/patient/find"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/patient/find/agents.md"
kind: "endpoints"
methods: [GET]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/patient/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/patient/find/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/patient/find/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/patient/find/use-case.md"
source_version: "43d07c0335624b7661c2872315a5f184e8c3d832"
extractor_model: "gpt-4o-2024-08-06"
extractor_prompt_version: "2026-08-13.v1"
reconciler_model: "claude-sonnet-4-6"
reconciler_prompt_version: "2026-08-13.v1"
generated_at: "2026-08-27T01:13:03.949984+00:00"
---

# /v3/patient/find

**URL**: https://demo.1health.io/api/v3/patient/find

_No description available in the API specification._

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/find | GET | Find patients matching demographic criteria |

---

## GET /v3/patient/find

Find patients matching demographic criteria

### Overview

Looks up patients by demographic criteria and returns a ranked list of candidates, each with a confidence score. Use it before creating a patient to check whether the person already exists, or any time you need to resolve a person to a patient ID. This operation is read-only and never creates or modifies a patient.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| firstName | String | No |  | Given name to match. |
| lastName | String | No |  | Family name to match. |
| dob | String | No |  | Date of birth in YYYY-MM-DD format. |
| sexAtBirth | String | No |  | Biological sex at birth. Non-discriminating when omitted or unknown. |
| exact | boolean | No | false | When true, returns only exact matches (score 1.0). Defaults to false (fuzzy matching). |

### Responses

#### 200 OK

Ranked list of matching patients (possibly empty).

**DTO**: `PatientFindResponseDTO`

```json
{
  "patients": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| patients | List<PatientMatchDTO> | Yes | The matching patient candidates. Empty when no patient meets the criteria. |

#### 400 Bad Request

Invalid request. Possible causes: • No demographic criteria provided (firstName, lastName, dob, or sexAtBirth) • Invalid sexAtBirth value • Invalid date format for dob

#### 401 Unauthorized

Not authenticated — valid session required.

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient/find" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Navigation
Parent: https://agents.1health.io/public/demo/api/v3/patient/agents.md · Site guide: https://agents.1health.io/public/demo/api/agents.md