Patient Vault — 1health

Address

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

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

APIs for managing patient physical addresses. Supports creating, listing, updating, and deactivating address records with automatic address validation.

Endpoints

Endpoint	Method	Description
/v3/patient/{patientId}/address	GET	List patient addresses
/v3/patient/{patientId}/address	POST	Add a new address to a patient
/v3/patient/{patientId}/address/{addressId}	GET	Get a specific patient address
/v3/patient/{patientId}/address/{addressId}	PUT	Fully update a patient address
/v3/patient/{patientId}/address/{addressId}	PATCH	Partially update a patient address
/v3/patient/{patientId}/address/{addressId}	DELETE	Deactivate a patient address

GET/v3/patient/{patientId}/address

List patient addresses

Overview

Returns all active addresses for a patient. Supports optional filtering by primary status and use type. Returns an array of address records (possibly empty). Only active (non-deleted) addresses are returned. Use ?primary=true to get only the primary address. Use ?use=home to filter by address use type.

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
primary	Boolean	No		Filter by primary status. When true, returns only the primary address.
use	String	No		Filter by address use type.

Responses

200 OK

List of patient addresses.

DTO: PatientAddressListResponseDTO

{
  "addresses": [
    {}
  ]
}

Field	Type	Nullable	Description
addresses	List	No	List of patient address records.

400 Bad Request

Invalid use filter value.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found.

Example

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

POST/v3/patient/{patientId}/address

Add a new address to a patient

Overview

Appends a new physical address to the patient record. Old addresses are preserved for audit trail. The address is validated against the Google Address Validation API. Creates a new address record — existing addresses are not modified. If primary is set to true, any existing primary address is automatically unset. If this is the patient's first address and primary is not specified, it is automatically set as primary. Address validation is performed automatically. The validationStatus field indicates the result: verified, unverified, or unknown. If validation returns unverified, candidate suggestions may be included in validationCandidates. Addresses are never rejected on validation grounds — the record is always created. effectiveFrom defaults to the current date if not provided. country defaults to United States if not provided. Requires authentication. Required fields: line1, city, state, postalCode. use defaults to work if not provided.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient to add an address to.

Request Body

Content-Type: application/json · DTO: PatientAddressRequestDTO

{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
use	string	Yes	allowableValues: home, work, billing, mailing, temporary	Address use type.
line1	string	Yes		Street address line 1. Cannot be cleared.
line2	string	No		Apt, suite, unit, floor. Optional; clear with `n/a`.
city	string	Yes		City or municipality. Cannot be cleared.
state	string	Yes		State / province / region code. Cannot be cleared.
postalCode	string	Yes		ZIP or postal code. Cannot be cleared.
country	string	No		Country name. Valid country names available from /v2/public/countries.
primary	boolean	No		Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary).
effectiveFrom	string	No	format: date	When this address became valid in YYYY-MM-DD format. Defaults to current date.
effectiveTo	string	No	format: date	When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective).

Responses

201 Created

Address created successfully.

DTO: PatientAddressResponseDTO

{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}

Field	Type	Nullable	Description
id	Long	No	Address record ID.
use	String	No	Address use type.
line1	String	No	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	No	City or municipality.
state	String	No	State / province / region code.
postalCode	String	No	ZIP or postal code.
country	String	Yes	Country name.
primary	Boolean	Yes	Whether this is the primary address.
effectiveFrom	LocalDate	Yes	When this address became valid.
effectiveTo	LocalDate	Yes	When this address stopped being valid. Null means current.
validationStatus	String	Yes	Address validation status.
validationCandidates	List<Map<String, String>>	Yes	Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'.

400 Bad Request

Invalid request. Possible causes: A required field (line1, city, state, postalCode) is missing, blank, or set to n/a; Invalid use value; Invalid date format for effectiveFrom or effectiveTo; effectiveTo is before effectiveFrom

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient not found.

Example

curl -X POST "https://demo.1health.io/api/v3/patient/1001/address" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

GET/v3/patient/{patientId}/address/{addressId}

Get a specific patient address

Overview

Returns a single address record for a patient. Requires authentication. Returns 404 if the address ID is not found for this patient.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

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

Responses

200 OK

Address record found.

DTO: PatientAddressResponseDTO

{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}

Field	Type	Nullable	Description
id	Long	No	Address record ID.
use	String	No	Address use type.
line1	String	No	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	No	City or municipality.
state	String	No	State / province / region code.
postalCode	String	No	ZIP or postal code.
country	String	Yes	Country name.
primary	Boolean	Yes	Whether this is the primary address.
effectiveFrom	LocalDate	Yes	When this address became valid.
effectiveTo	LocalDate	Yes	When this address stopped being valid. Null means current.
validationStatus	String	Yes	Address validation status.
validationCandidates	List<Map<String, String>>	Yes	Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Address not found — re-fetch the list to find the current record.

Example

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

PUT/v3/patient/{patientId}/address/{addressId}

Fully update a patient address

Overview

Replaces all fields of an existing address record. All required fields must be provided. Re-validation is triggered if address data has changed or the current status is unknown. If primary is changed to true, the previous primary address is automatically unset. Address validation is re-triggered when address fields change or the current validationStatus is unknown. Requires authentication. Returns 404 if the address does not exist for this patient.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
addressId	Long	Yes	The ID of the address record to update.

Request Body

Content-Type: application/json · DTO: PatientAddressRequestDTO

{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
use	string	Yes	allowableValues: home, work, billing, mailing, temporary	Address use type.
line1	string	Yes		Street address line 1. Cannot be cleared.
line2	string	No		Apt, suite, unit, floor. Optional; clear with `n/a`.
city	string	Yes		City or municipality. Cannot be cleared.
state	string	Yes		State / province / region code. Cannot be cleared.
postalCode	string	Yes		ZIP or postal code. Cannot be cleared.
country	string	No		Country name. Valid country names available from /v2/public/countries.
primary	boolean	No		Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary).
effectiveFrom	string	No	format: date	When this address became valid in YYYY-MM-DD format. Defaults to current date.
effectiveTo	string	No	format: date	When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective).

Responses

200 OK

Address updated successfully.

DTO: PatientAddressResponseDTO

{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}

Field	Type	Nullable	Description
id	Long	No	Address record ID.
use	String	No	Address use type.
line1	String	No	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	No	City or municipality.
state	String	No	State / province / region code.
postalCode	String	No	ZIP or postal code.
country	String	Yes	Country name.
primary	Boolean	Yes	Whether this is the primary address.
effectiveFrom	LocalDate	Yes	When this address became valid.
effectiveTo	LocalDate	Yes	When this address stopped being valid. Null means current.
validationStatus	String	Yes	Address validation status.
validationCandidates	List<Map<String, String>>	Yes	Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'.

400 Bad Request

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or address not found.

Example

curl -X PUT "https://demo.1health.io/api/v3/patient/1001/address/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

PATCH/v3/patient/{patientId}/address/{addressId}

Partially update a patient address

Overview

Updates only the fields provided in the request body. Fields not included are left unchanged. Re-validation is triggered if address fields change or the current status is unknown. Only non-null fields are applied. Existing values for omitted fields are preserved. Sending null (or omitting a field) leaves it unchanged, so an optional field is cleared by sending the default value for its type: Text (line2) — send n/a; Date (effectiveTo) — send 1970-01-01 to clear the end date so the address is treated as currently effective; Boolean (primary) — send false to unset it (allowed only when another address is already primary); effectiveFrom cannot be emptied; sending it blank resets it to the current date; line1, city, state and postalCode are required and cannot be cleared.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

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

Request Body

Content-Type: application/json · DTO: PatientAddressRequestDTO

{
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
use	string	Yes	allowableValues: home, work, billing, mailing, temporary	Address use type.
line1	string	Yes		Street address line 1. Cannot be cleared.
line2	string	No		Apt, suite, unit, floor. Optional; clear with `n/a`.
city	string	Yes		City or municipality. Cannot be cleared.
state	string	Yes		State / province / region code. Cannot be cleared.
postalCode	string	Yes		ZIP or postal code. Cannot be cleared.
country	string	No		Country name. Valid country names available from /v2/public/countries.
primary	boolean	No		Mark as primary address. Only one can be primary at a time. Send `false` to unset (another address must already be primary).
effectiveFrom	string	No	format: date	When this address became valid in YYYY-MM-DD format. Defaults to current date.
effectiveTo	string	No	format: date	When this address stopped being valid in YYYY-MM-DD format. Null means current. Send `1970-01-01` to clear the end date (address treated as currently effective).

Responses

200 OK

Address partially updated successfully.

DTO: PatientAddressResponseDTO

{
  "id": 1001,
  "use": "example-value",
  "line1": "example-value",
  "line2": "example-value",
  "city": "example-value",
  "state": "example-value",
  "postalCode": "example-value",
  "country": "example-value",
  "primary": true,
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15",
  "validationStatus": "example-value",
  "validationCandidates": [
    {}
  ]
}

Field	Type	Nullable	Description
id	Long	No	Address record ID.
use	String	No	Address use type.
line1	String	No	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	No	City or municipality.
state	String	No	State / province / region code.
postalCode	String	No	ZIP or postal code.
country	String	Yes	Country name.
primary	Boolean	Yes	Whether this is the primary address.
effectiveFrom	LocalDate	Yes	When this address became valid.
effectiveTo	LocalDate	Yes	When this address stopped being valid. Null means current.
validationStatus	String	Yes	Address validation status.
validationCandidates	List<Map<String, String>>	Yes	Candidate addresses suggested by the validation service. Only populated when validationStatus is 'unverified'.

400 Bad Request

Invalid request. Possible causes: Invalid use value; Invalid date format for effectiveFrom or effectiveTo; effectiveTo is before effectiveFrom; Attempting to clear a required field (line1, city, state, postalCode); Cannot unset primary without setting another address as primary first

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or address not found.

Example

curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/address/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"use": "example-value", "line1": "example-value", "line2": "example-value", "city": "example-value", "state": "example-value", "postalCode": "example-value", "country": "example-value", "primary": true, "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

DELETE/v3/patient/{patientId}/address/{addressId}

Deactivate a patient address

Overview

Soft-deletes an address record. The address is deactivated but preserved for audit trail. Requires authentication. Cannot delete a primary address — first set another address as primary. Returns 404 if the address does not exist.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
patientId	Long	Yes	The ID of the patient.
addressId	Long	Yes	The ID of the address record to deactivate.

Responses

200 OK

Address deactivated successfully.

DTO: OneHealthResponseDTO

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

Field	Type	Nullable	Description
id	Long	Yes
name	String	Yes	DTO containing name
message	String	Yes

400 Bad Request

Cannot delete primary address — set another as primary first.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or address not found.

Example

curl -X DELETE "https://demo.1health.io/api/v3/patient/1001/address/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

Address

Endpoints

GET/v3/patient/{patientId}/address

Overview

Authorization

Path Parameters

Query Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

POST/v3/patient/{patientId}/address

Overview

Authorization

Path Parameters

Request Body

Responses

201 Created

400 Bad Request

401 Unauthorized

404 Not Found

Example

GET/v3/patient/{patientId}/address/{addressId}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

PUT/v3/patient/{patientId}/address/{addressId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

PATCH/v3/patient/{patientId}/address/{addressId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

DELETE/v3/patient/{patientId}/address/{addressId}

Overview

Authorization

Path Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

Navigation