Patient Vault — 1health

Patients

/v3/patient endpoint reference.

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

REST API for managing patient demographic records in the Patient Vault. Provides create, full update, partial update, and delete operations for patient demographic information including name, date of birth, gender, race, ethnicity, and SSN.

Endpoints

Endpoint	Method	Description
/v3/patient	GET	List patient records
/v3/patient	POST	Create a patient record
/v3/patient/{id}	GET	Get a patient record by ID
/v3/patient/{id}	PUT	Fully update a patient record
/v3/patient/{id}	PATCH	Partially update a patient record
/v3/patient/{id}	DELETE	Delete a patient record

GET/v3/patient

List patient records

Overview

Returns a paginated list of patient demographic records for the current tenant's organization. Each entry carries the same demographic fields as the single-patient endpoint. Only patients of the caller's organization are returned. Soft-deleted patients are excluded. Results are returned page by page; use page and size to navigate. Returns 200 with an empty list when the organization has no patients — not a 404. Requires authentication. page is zero-based and defaults to 0. size defaults to 50.

Authorization

Bearer JWT required. See the authentication guide.

Query Parameters

Parameter	Type	Required	Default	Description
page	int	No	0	Zero-based page index to retrieve. Defaults to 0 when omitted.
size	int	No	50	Number of records per page. Defaults to 50 when omitted.

Responses

200 OK

Paginated list of patient records (possibly empty).

DTO: Page<PatientResponseDTO>

{
  "data": [
    {}
  ],
  "pageNumber": 1,
  "pageSize": 1,
  "offset": 1001,
  "emptyPage": true,
  "firstPage": true,
  "lastPage": true,
  "numberOfElements": 1001,
  "totalElements": 1001,
  "totalPages": 1
}

Field	Type	Nullable
data	List	No
pageNumber	int	No
pageSize	int	No
offset	long	No
emptyPage	boolean	No
firstPage	boolean	No
lastPage	boolean	No
numberOfElements	long	No
totalElements	long	No
totalPages	int	No

401 Unauthorized

Not authenticated — valid session required.

Example

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

POST/v3/patient

Create a patient record

Overview

Creates a new patient demographic record in the Patient Vault. Required fields are first name, last name, and date of birth. Enum fields (gender, race, ethnicity) default to Unknown if not provided. The Patient Vault never decides whether two records are the same person, and never blocks or merges based on similarity. Every call creates a new, distinct patient — even when an identical record (same firstName, lastName, and dob, and even the same last4Ssn, race, and ethnicity) already exists in the tenant. No SSN, race, or ethnicity is ever required to disambiguate. Use the patient find/match API to detect and resolve potential duplicates yourself. If last4Ssn is provided, it is stored in masked format (e.g. *--1234) — the full SSN is never stored or returned. All value-list fields (gender, race, ethnicity) are validated against their allowed values. Requires authentication. Date fields must be in YYYY-MM-DD format. Date of birth cannot be in the future. Deceased status is read-only here — manage it via the /v3/patient/{patientId}/deceased endpoints.

Authorization

Bearer JWT required. See the authentication guide.

Request Body

Content-Type: application/json · DTO: PatientRequestDTO

{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}

Field	Type	Required	Constraints	Description
firstName	string	Yes	Cannot be cleared.	Legal first name.
lastName	string	Yes	Cannot be cleared.	Legal last name / surname.
middleName	string	No	Optional; clear with `n/a`.	Middle name or initial.
dob	string	Yes	Cannot be cleared.	Date of birth in YYYY-MM-DD format.
gender	string	No	Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown.	Administrative sex.
genderIdentity	string	No	Optional; clear with `n/a`.	Self-reported gender identity (freeform or coded).
sexAtBirth	string	No	Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown.	Biological sex at birth.
race	string	No	Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown.	OMB race category.
ethnicity	string	No	Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown.	OMB ethnicity category.
preferredLanguage	string	No	Optional; clear with `n/a`.	Free form language name.
last4Ssn	string	No	Must be exactly 4 numeric digits. Cannot be cleared.	Last 4 digits of Social Security Number.

Responses

200 OK

Patient record created successfully.

DTO: PatientResponseDTO

{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}

Field	Type	Nullable	Description
id	Long	No	Person instance ID.
firstName	String	No	Legal first name.
lastName	String	No	Legal last name / surname.
middleName	String	Yes	Middle name or initial.
dob	String	No	Date of birth (YYYY-MM-DD).
gender	String	Yes	Administrative sex.
genderIdentity	String	Yes	Self-reported gender identity.
sexAtBirth	String	Yes	Biological sex at birth.
race	String	Yes	OMB race category.
ethnicity	String	Yes	OMB ethnicity category.
preferredLanguage	String	Yes	Preferred language.
ssnPreview	String	Yes	Masked SSN preview. Only last 4 digits shown.
updatedBy	String	Yes	User who last updated the patient record.
updated	LocalDateTime	Yes	Timestamp of the last update.

400 Bad Request

Invalid request. Possible causes: A required field (firstName, lastName, dob) is missing, blank, or set to n/a; Invalid value for gender, race, or ethnicity; Invalid date format for dob; Date of birth is in the future; last4Ssn is not exactly 4 digits

401 Unauthorized

Not authenticated — valid session required.

Example

curl -X POST "https://demo.1health.io/api/v3/patient" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'

GET/v3/patient/{id}

Get a patient record by ID

Overview

Returns the demographic record of a single patient by ID. The response carries the same fields as each entry in the patient list. Returns the patient's demographics including name, date of birth, gender, race, ethnicity, preferred language, and masked SSN preview. The full SSN is never returned — only the masked preview (e.g. *--1234). Requires authentication. Idempotent — repeated calls return the same result. Returns 404 if the patient does not exist in the current tenant.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
id	Long	Yes	The ID of the patient record to retrieve.

Responses

200 OK

Patient record found.

DTO: PatientResponseDTO

{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}

Field	Type	Nullable	Description
id	Long	No	Person instance ID.
firstName	String	No	Legal first name.
lastName	String	No	Legal last name / surname.
middleName	String	Yes	Middle name or initial.
dob	String	No	Date of birth (YYYY-MM-DD).
gender	String	Yes	Administrative sex.
genderIdentity	String	Yes	Self-reported gender identity.
sexAtBirth	String	Yes	Biological sex at birth.
race	String	Yes	OMB race category.
ethnicity	String	Yes	OMB ethnicity category.
preferredLanguage	String	Yes	Preferred language.
ssnPreview	String	Yes	Masked SSN preview. Only last 4 digits shown.
updatedBy	String	Yes	User who last updated the patient record.
updated	LocalDateTime	Yes	Timestamp of the last update.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

Example

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

PUT/v3/patient/{id}

Fully update a patient record

Overview

Replaces all demographic fields of an existing patient record. All required fields must be provided. Optional fields omitted from the request will be cleared. All required fields (firstName, lastName, dob) must be present. Optional fields not included in the request body are set to null. Use PATCH instead if you only want to update specific fields without clearing others. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
id	Long	Yes	The ID of the patient record to update.

Request Body

Content-Type: application/json · DTO: PatientRequestDTO

{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}

Field	Type	Required	Constraints	Description
firstName	string	Yes	Cannot be cleared.	Legal first name.
lastName	string	Yes	Cannot be cleared.	Legal last name / surname.
middleName	string	No	Optional; clear with `n/a`.	Middle name or initial.
dob	string	Yes	Cannot be cleared.	Date of birth in YYYY-MM-DD format.
gender	string	No	Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown.	Administrative sex.
genderIdentity	string	No	Optional; clear with `n/a`.	Self-reported gender identity (freeform or coded).
sexAtBirth	string	No	Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown.	Biological sex at birth.
race	string	No	Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown.	OMB race category.
ethnicity	string	No	Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown.	OMB ethnicity category.
preferredLanguage	string	No	Optional; clear with `n/a`.	Free form language name.
last4Ssn	string	No	Must be exactly 4 numeric digits. Cannot be cleared.	Last 4 digits of Social Security Number.

Responses

200 OK

Patient record updated successfully.

DTO: PatientResponseDTO

{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}

Field	Type	Nullable	Description
id	Long	No	Person instance ID.
firstName	String	No	Legal first name.
lastName	String	No	Legal last name / surname.
middleName	String	Yes	Middle name or initial.
dob	String	No	Date of birth (YYYY-MM-DD).
gender	String	Yes	Administrative sex.
genderIdentity	String	Yes	Self-reported gender identity.
sexAtBirth	String	Yes	Biological sex at birth.
race	String	Yes	OMB race category.
ethnicity	String	Yes	OMB ethnicity category.
preferredLanguage	String	Yes	Preferred language.
ssnPreview	String	Yes	Masked SSN preview. Only last 4 digits shown.
updatedBy	String	Yes	User who last updated the patient record.
updated	LocalDateTime	Yes	Timestamp of the last update.

400 Bad Request

Invalid request. Possible causes: A required field (firstName, lastName, dob) is missing, blank, or set to n/a; Invalid value for gender, race, or ethnicity; Invalid date format; Date validation failures; last4Ssn is not exactly 4 digits

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

Example

curl -X PUT "https://demo.1health.io/api/v3/patient/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'

PATCH/v3/patient/{id}

Partially update a patient record

Overview

Updates only the fields provided in the request body. Fields not included in the request are left unchanged. Only non-null fields in the request body are applied to the patient record. Existing values for omitted fields are preserved. Value-list fields are validated only when provided. Sending null (or omitting a field) leaves it unchanged, so an optional field is cleared by sending the default value for its type: Text (middleName, genderIdentity, preferredLanguage) — send n/a; Coded (gender, race, ethnicity, sexAtBirth) — send n/a (or Unknown); the field resets to Unknown. firstName, lastName and dob are required and cannot be cleared; last4Ssn accepts only 4 digits and cannot be cleared. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
id	Long	Yes	The ID of the patient record to partially update.

Request Body

Content-Type: application/json · DTO: PatientRequestDTO

{
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "last4Ssn": "example-value"
}

Field	Type	Required	Constraints	Description
firstName	string	Yes	Cannot be cleared.	Legal first name.
lastName	string	Yes	Cannot be cleared.	Legal last name / surname.
middleName	string	No	Optional; clear with `n/a`.	Middle name or initial.
dob	string	Yes	Cannot be cleared.	Date of birth in YYYY-MM-DD format.
gender	string	No	Allowed values: Male, Female, Other, Unknown, Asked but not answered. Send `n/a` to reset to Unknown.	Administrative sex.
genderIdentity	string	No	Optional; clear with `n/a`.	Self-reported gender identity (freeform or coded).
sexAtBirth	string	No	Allowed values: Male, Female, Intersex, Unknown. Send `n/a` to reset to Unknown.	Biological sex at birth.
race	string	No	Allowed values: American Indian or Alaska Native, Asian, Black or African American, Hispanic or Latino, Middle Eastern or North African, Native Hawaiian or other Pacific Islander, White, Other Race, Unknown. Send `n/a` to reset to Unknown.	OMB race category.
ethnicity	string	No	Allowed values: Hispanic or Latino, Not Hispanic or Latino, Unknown. Send `n/a` to reset to Unknown.	OMB ethnicity category.
preferredLanguage	string	No	Optional; clear with `n/a`.	Free form language name.
last4Ssn	string	No	Must be exactly 4 numeric digits. Cannot be cleared.	Last 4 digits of Social Security Number.

Responses

200 OK

Patient record partially updated successfully.

DTO: PatientResponseDTO

{
  "id": 1001,
  "firstName": "example-value",
  "lastName": "example-value",
  "middleName": "example-value",
  "dob": "example-value",
  "gender": "example-value",
  "genderIdentity": "example-value",
  "sexAtBirth": "example-value",
  "race": "example-value",
  "ethnicity": "example-value",
  "preferredLanguage": "example-value",
  "ssnPreview": "example-value",
  "updatedBy": "example-value",
  "updated": "2024-01-15T09:30:00Z"
}

Field	Type	Nullable	Description
id	Long	No	Person instance ID.
firstName	String	No	Legal first name.
lastName	String	No	Legal last name / surname.
middleName	String	Yes	Middle name or initial.
dob	String	No	Date of birth (YYYY-MM-DD).
gender	String	Yes	Administrative sex.
genderIdentity	String	Yes	Self-reported gender identity.
sexAtBirth	String	Yes	Biological sex at birth.
race	String	Yes	OMB race category.
ethnicity	String	Yes	OMB ethnicity category.
preferredLanguage	String	Yes	Preferred language.
ssnPreview	String	Yes	Masked SSN preview. Only last 4 digits shown.
updatedBy	String	Yes	User who last updated the patient record.
updated	LocalDateTime	Yes	Timestamp of the last update.

400 Bad Request

Invalid request. Possible causes: Invalid value for gender, race, or ethnicity; Invalid date format for dob; Date of birth is in the future; last4Ssn is not exactly 4 digits

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

Example

curl -X PATCH "https://demo.1health.io/api/v3/patient/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"firstName": "example-value", "lastName": "example-value", "middleName": "example-value", "dob": "example-value", "gender": "example-value", "genderIdentity": "example-value", "sexAtBirth": "example-value", "race": "example-value", "ethnicity": "example-value", "preferredLanguage": "example-value", "last4Ssn": "example-value"}'

DELETE/v3/patient/{id}

Delete a patient record

Overview

Soft-deletes a patient record. The record is marked as deleted but not permanently removed. The patient record is soft-deleted and will no longer appear in queries. Requires authentication. Returns 404 if the patient does not exist in the current tenant.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
id	Long	Yes	The ID of the patient record to delete.

Responses

200 OK

Patient record deleted successfully.

DTO: OneHealthResponseDTO

{
  "id": 1001,
  "name": "example-value",
  "message": "example-value"
}

Field	Type	Nullable
id	Long	Yes
name	String	Yes
message	String	Yes

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Not found — patient with the specified ID does not exist in this tenant.

Example

curl -X DELETE "https://demo.1health.io/api/v3/patient/1001" \
  -H "Authorization: Bearer $TOKEN"

Child Routes

Path	Methods	Summary	agents.md
/v3/patient/find	GET		https://agents.1health.io/public/demo/api/v3/patient/find/agents.md
/v3/patient/{patientId}	—	address, alias, attach, contact, deceased, identifier	https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md

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

Patients

Endpoints

GET/v3/patient

Overview

Authorization

Query Parameters

Responses

200 OK

401 Unauthorized

Example

POST/v3/patient

Overview

Authorization

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

Example

GET/v3/patient/{id}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

PUT/v3/patient/{id}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

PATCH/v3/patient/{id}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

DELETE/v3/patient/{id}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

Child Routes

Navigation