Patient Vault — 1health

Address

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

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

REST API for managing patient physical addresses in the Patient Vault. Provides full CRUD operations for patient address records including Google Address Validation integration for address standardization.

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.

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.

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	Yes	Address use type.
line1	String	Yes	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	Yes	City or municipality.
state	String	Yes	State / province / region code.
postalCode	String	Yes	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.

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	Yes	Address use type.
line1	String	Yes	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	Yes	City or municipality.
state	String	Yes	State / province / region code.
postalCode	String	Yes	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.

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	Yes	Address use type.
line1	String	Yes	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	Yes	City or municipality.
state	String	Yes	State / province / region code.
postalCode	String	Yes	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.

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	Yes	Address use type.
line1	String	Yes	Street address line 1.
line2	String	Yes	Apt, suite, unit, floor.
city	String	Yes	City or municipality.
state	String	Yes	State / province / region code.
postalCode	String	Yes	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.

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