# /v3/patient/find

`GET`


Manages patient demographic records in the Patient Vault: list all patients, retrieve a single patient by ID, find patients by demographic criteria, create a new patient record, fully replace a patient record, partially update a patient record, and soft-delete a patient record.

**Authentication**: Bearer JWT required for all endpoints.

## Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/find` | GET | Find patients by demographic criteria (fuzzy) |

---

## GET /v3/patient/find

## Endpoint Details

| Property | Value |
|----------|-------|
| **URL** | `/v3/patient/find` |
| **Method** | `GET` |
| **Authentication** | Required — valid session |
| **Content-Type** | `application/json` |

## Query Parameters


### GET /v3/patient/find

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `firstName` | String | — | Given name to match. |
| `lastName` | String | — | Family name to match. |
| `dob` | String | — | Date of birth in `YYYY-MM-DD` format. |
| `sexAtBirth` | String | — | Biological sex at birth. Allowed values: `male`, `female`, `intersex`, `unknown`. Non-discriminating when omitted or `unknown`. |
| `exact` | Boolean | `false` | When `true`, returns only exact matches (score `1.0`). When `false`, uses fuzzy matching. |



## Response


### Success Response (200 OK)

**GET /v3/patient/find** — **DTO**: `PatientFindResponseDTO`

```json
{
  "results": [
    {
      "patient": {
        "id": 12345,
        "firstName": "Maria",
        "lastName": "Santos",
        "dob": "1988-04-12"
      },
      "score": 0.95,
      "matchedOn": ["firstName", "lastName", "dob"]
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `results` | List | Ranked list of matching patient candidates. Empty list when no match is found. |
| `results[].patient` | PatientResponseDTO | Patient demographic record. |
| `results[].score` | Double | Confidence score between `0` and `1`. Exact matches return `1.0`. |
| `results[].matchedOn` | List\<String\> | Criteria that contributed to the match. |

---

### Error Responses

| Status | Condition | Response |
|--------|-----------|----------|
| 400 | `firstName`, `lastName`, or `dob` is missing, blank, or `n/a` (POST/PUT) | Validation error with message |
| 400 | Invalid value for `gender`, `race`, or `ethnicity` | Validation error with message |
| 400 | Invalid date format for `dob` | Validation error with message |
| 400 | Date of birth is in the future | Validation error with message |
| 400 | `last4Ssn` is not exactly 4 digits | Validation error with message |
| 400 | No demographic criteria provided to `/find` (GET) | Validation error with message |
| 400 | Invalid `sexAtBirth` value supplied to `/find` | Validation error with message |
| 401 | No valid session | Not authenticated |
| 404 | Patient with the specified ID does not exist in the current tenant (GET by ID, PUT, PATCH, DELETE) | Not found error with message |



## Example Request


### GET /v3/patient/find — Find patients by demographic criteria (fuzzy)

```bash
curl -X GET "https://demo.1health.io/v3/patient/find?firstName=Maria&lastName=Santos&dob=1988-04-12&sexAtBirth=female&exact=false"
```

### GET /v3/patient/find — Find patients by demographic criteria (exact)

```bash
curl -X GET "https://demo.1health.io/v3/patient/find?firstName=Maria&lastName=Santos&dob=1988-04-12&exact=true"
```



## Related Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v3/patient/{patientId}/deceased` | GET | Retrieve the deceased status of a patient. |
| `/v3/patient/{patientId}/deceased` | POST | Mark a patient as deceased. |
| `/v3/patient/{patientId}/deceased` | DELETE | Remove the deceased status from a patient. |

---