Patient Vault — 1health

Contact

/v3/patient/{patientId}/contact endpoint reference.

URL: https://demo.1health.io/api/v3/patient/{patientId}/contact

APIs for managing patient contact points (email, phone, fax). Supports creating, listing, updating, and deactivating contact points. The collection is append-only — old contact points are retained for audit and outreach history.

Endpoints

Endpoint	Method	Description
/v3/patient/{patientId}/contact	GET	List patient contact points
/v3/patient/{patientId}/contact	POST	Add a new contact point to a patient
/v3/patient/{patientId}/contact/{contactId}	GET	Get a specific patient contact point
/v3/patient/{patientId}/contact/{contactId}	PUT	Fully update a patient contact point
/v3/patient/{patientId}/contact/{contactId}	PATCH	Partially update a patient contact point
/v3/patient/{patientId}/contact/{contactId}	DELETE	Deactivate a patient contact point

GET/v3/patient/{patientId}/contact

List patient contact points

Overview

Returns all active contact points for a patient. Supports optional filtering by type and primary status.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.

Query Parameters

Parameter	Type	Required	Default	Description
type	String	No		Filter by contact point type.
primary	Boolean	No		When true, returns only primary contact points.

Responses

200 OK

List of patient contact points.

DTO: PatientContactListResponseDTO

{
  "contacts": [
    {}
  ]
}

Field	Type	Nullable	Description
contacts	List	No	List of contact point records.

400 Bad Request

Invalid type filter value.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

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

POST/v3/patient/{patientId}/contact

Add a new contact point to a patient

Overview

Appends a new contact point to the patient record. Old contact points are preserved for audit trail — each call creates a new record with its own ID.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient to add a contact point to.

Request Body

Content-Type: application/json · DTO: PatientContactRequestDTO

{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	Cannot be cleared.	The type of contact point. Cannot be cleared.
value	string	Yes	Cannot be cleared.	The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100).
label	string	No	Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).
isPrimary	boolean	No	Only one contact point per type can be primary at a time.	Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary.
notificationsEnabled	boolean	No	Defaults to `false`.	Whether this contact point may receive notifications. Defaults to `false`.
region	string	No	Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).

Responses

201 Created

Contact point created successfully.

DTO: PatientContactResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Nullable	Description
id	Long	Yes	Contact point record ID.
type	String	Yes	The type of contact point.
value	String	Yes	The address or number for this contact point.
label	String	Yes	Free-text label for this contact point.
isPrimary	Boolean	Yes	Whether this is the preferred contact point for its type.
notificationsEnabled	Boolean	Yes	Whether this contact point may receive notifications.
region	String	Yes	Region hint for phone normalization.

400 Bad Request

Invalid request. Possible causes: • A required field (type, value) is missing, blank, or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

curl -X POST "https://demo.1health.io/api/v3/patient/1001/contact" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'

GET/v3/patient/{patientId}/contact/{contactId}

Get a specific patient contact point

Overview

Returns a single contact point for a patient.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
contactId	Long	Yes	The ID of the contact point record.

Responses

200 OK

Contact point found.

DTO: PatientContactResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Nullable	Description
id	Long	Yes	Contact point record ID.
type	String	Yes	The type of contact point.
value	String	Yes	The address or number for this contact point.
label	String	Yes	Free-text label for this contact point.
isPrimary	Boolean	Yes	Whether this is the preferred contact point for its type.
notificationsEnabled	Boolean	Yes	Whether this contact point may receive notifications.
region	String	Yes	Region hint for phone normalization.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Contact point not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

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

PUT/v3/patient/{patientId}/contact/{contactId}

Fully update a patient contact point

Overview

Replaces all fields of an existing contact point. Required fields must be provided; optional fields absent or sent blank are reset to their default value.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
contactId	Long	Yes	The ID of the contact point to update.

Request Body

Content-Type: application/json · DTO: PatientContactRequestDTO

{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	Cannot be cleared.	The type of contact point. Cannot be cleared.
value	string	Yes	Cannot be cleared.	The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100).
label	string	No	Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).
isPrimary	boolean	No	Only one contact point per type can be primary at a time.	Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary.
notificationsEnabled	boolean	No	Defaults to `false`.	Whether this contact point may receive notifications. Defaults to `false`.
region	string	No	Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).

Responses

200 OK

Contact point updated successfully.

DTO: PatientContactResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Nullable	Description
id	Long	Yes	Contact point record ID.
type	String	Yes	The type of contact point.
value	String	Yes	The address or number for this contact point.
label	String	Yes	Free-text label for this contact point.
isPrimary	Boolean	Yes	Whether this is the preferred contact point for its type.
notificationsEnabled	Boolean	Yes	Whether this contact point may receive notifications.
region	String	Yes	Region hint for phone normalization.

400 Bad Request

Invalid request. Possible causes: • A required field (type, value) is missing, blank, or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or contact point not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

curl -X PUT "https://demo.1health.io/api/v3/patient/1001/contact/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'

PATCH/v3/patient/{patientId}/contact/{contactId}

Partially update a patient contact point

Overview

Updates only the fields sent in the request body. Fields that are omitted or sent as null are left unchanged.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
contactId	Long	Yes	The ID of the contact point to partially update.

Request Body

Content-Type: application/json · DTO: PatientContactRequestDTO

{
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	Cannot be cleared.	The type of contact point. Cannot be cleared.
value	string	Yes	Cannot be cleared.	The address or number for this contact point. Cannot be cleared. Email values are format-checked; phone values (mobile, fax) are validated for the region and stored in E.164 format (e.g. +14155550100).
label	string	No	Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Free-text label for this contact point. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).
isPrimary	boolean	No	Only one contact point per type can be primary at a time.	Marks this as the preferred contact point for its type. Only one contact point per type can be primary at a time. Send `false` to make it non-primary.
notificationsEnabled	boolean	No	Defaults to `false`.	Whether this contact point may receive notifications. Defaults to `false`.
region	string	No	Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).	Region used to validate and normalize phone numbers, e.g. "us". Defaults to "us" for phone types (mobile, fax) when blank. Ignored for non-phone types. Optional; clear with `n/a` (a blank value is also normalized to `n/a`).

Responses

200 OK

Contact point partially updated successfully.

DTO: PatientContactResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "value": "example-value",
  "label": "example-value",
  "isPrimary": true,
  "notificationsEnabled": true,
  "region": "example-value"
}

Field	Type	Nullable	Description
id	Long	Yes	Contact point record ID.
type	String	Yes	The type of contact point.
value	String	Yes	The address or number for this contact point.
label	String	Yes	Free-text label for this contact point.
isPrimary	Boolean	Yes	Whether this is the preferred contact point for its type.
notificationsEnabled	Boolean	Yes	Whether this contact point may receive notifications.
region	String	Yes	Region hint for phone normalization.

400 Bad Request

Invalid request. Possible causes: • A required field (type, value) sent blank or set to n/a • Invalid type value • Invalid email address, or invalid phone number for the given region

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or contact point not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/contact/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "value": "example-value", "label": "example-value", "isPrimary": true, "notificationsEnabled": true, "region": "example-value"}'

DELETE/v3/patient/{patientId}/contact/{contactId}

Deactivate a patient contact point

Overview

Soft-deletes a contact point. The record is deactivated but preserved for outreach history.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
contactId	Long	Yes	The ID of the contact point to deactivate.

Responses

200 OK

Contact point deactivated successfully.

DTO: PatientContactDeleteResponseDTO

{
  "id": 1001,
  "active": true,
  "deletedAt": "2024-01-15T09:30:00Z"
}

Field	Type	Nullable	Description
id	Long	No	The ID of the deactivated contact point.
active	boolean	No	Whether the contact point is active.
deletedAt	LocalDateTime	No	Timestamp when the contact point was deactivated.

400 Bad Request

Cannot delete a primary contact point — promote another of the same type first.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or contact point not found.

500 Internal Server Error

Unexpected error while processing the contact point request.

Example

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

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

Contact

Endpoints

GET/v3/patient/{patientId}/contact

Overview

Authorization

Path Parameters

Query Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

POST/v3/patient/{patientId}/contact

Overview

Authorization

Path Parameters

Request Body

Responses

201 Created

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

GET/v3/patient/{patientId}/contact/{contactId}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

PUT/v3/patient/{patientId}/contact/{contactId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

PATCH/v3/patient/{patientId}/contact/{contactId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

DELETE/v3/patient/{patientId}/contact/{contactId}

Overview

Authorization

Path Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Example

Navigation