Patient Vault — 1health

Alias

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

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

APIs for managing patient name aliases. Supports creating, listing, updating, and deactivating alternate name records (maiden names, nicknames, legal changes, etc.).

Endpoints

Endpoint	Method	Description
/v3/patient/{patientId}/alias	GET	List patient name aliases
/v3/patient/{patientId}/alias	POST	Add a new name alias to a patient
/v3/patient/{patientId}/alias/{aliasId}	GET	Get a specific patient name alias
/v3/patient/{patientId}/alias/{aliasId}	PUT	Fully update a patient name alias
/v3/patient/{patientId}/alias/{aliasId}	PATCH	Partially update a patient name alias
/v3/patient/{patientId}/alias/{aliasId}	DELETE	Deactivate a patient name alias

GET/v3/patient/{patientId}/alias

List patient name aliases

Overview

Returns all active name aliases for a patient. Returns an array of alias records (possibly empty). Only active (non-deleted) aliases are returned.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

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

Responses

200 OK

List of patient name aliases.

DTO: PatientAliasListResponseDTO

{
  "aliases": [
    {}
  ]
}

Field	Type	Nullable	Description
aliases	List	No	List of name alias records.

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/alias" \
  -H "Authorization: Bearer $TOKEN"

POST/v3/patient/{patientId}/alias

Add a new name alias to a patient

Overview

Creates a new name alias record for a patient. Used to track alternate names such as maiden names, nicknames, legal name changes, or preferred names. Creates a new alias record — existing aliases are not modified. At least one of alias, firstName, lastName, or fullName must be provided. type is required and must be one of: maiden, nickname, preferred, previous, legal_change, alias. Requires authentication.

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 alias to.

Request Body

Content-Type: application/json · DTO: PatientAliasRequestDTO

{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	allowableValues: maiden, nickname, preferred, previous, legal_change, alias	Type of name alias.
alias	string	No		Alias or nickname.
firstName	string	No		Alternate first name.
lastName	string	No		Alternate last name.
fullName	string	No		Full alternate name for mononyms or cultural formats.
effectiveFrom	string	No	format: date	When this name was in use in YYYY-MM-DD format.
effectiveTo	string	No	format: date	When this name stopped being used in YYYY-MM-DD format.

Responses

201 Created

Alias created successfully.

DTO: PatientAliasResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}

Field	Type	Nullable	Description
id	Long	No	Alias record ID.
type	String	No	Type of name alias.
alias	String	Yes	Alias or nickname.
firstName	String	Yes	Alternate first name.
lastName	String	Yes	Alternate last name.
fullName	String	Yes	Full alternate name.
effectiveFrom	LocalDate	Yes	When this name was in use.
effectiveTo	LocalDate	Yes	When this name stopped being used.

400 Bad Request

Invalid request. Possible causes: Missing required field (type), No name field provided (alias, firstName, lastName, or fullName), Invalid type value, 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/alias" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

GET/v3/patient/{patientId}/alias/{aliasId}

Get a specific patient name alias

Overview

Returns a single name alias record for a patient. Requires authentication. Returns 404 if the alias 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.
aliasId	Long	Yes	The ID of the alias record.

Responses

200 OK

Alias record found.

DTO: PatientAliasResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}

Field	Type	Nullable	Description
id	Long	No	Alias record ID.
type	String	No	Type of name alias.
alias	String	Yes	Alias or nickname.
firstName	String	Yes	Alternate first name.
lastName	String	Yes	Alternate last name.
fullName	String	Yes	Full alternate name.
effectiveFrom	LocalDate	Yes	When this name was in use.
effectiveTo	LocalDate	Yes	When this name stopped being used.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

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

Example

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

PUT/v3/patient/{patientId}/alias/{aliasId}

Fully update a patient name alias

Overview

Replaces all fields of an existing alias record. The type field and at least one name field are required. All required fields must be present in the request. Fields not provided will be cleared. Requires authentication. Returns 404 if the alias 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.
aliasId	Long	Yes	The ID of the alias record to update.

Request Body

Content-Type: application/json · DTO: PatientAliasRequestDTO

{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	allowableValues: maiden, nickname, preferred, previous, legal_change, alias	Type of name alias.
alias	string	No		Alias or nickname.
firstName	string	No		Alternate first name.
lastName	string	No		Alternate last name.
fullName	string	No		Full alternate name for mononyms or cultural formats.
effectiveFrom	string	No	format: date	When this name was in use in YYYY-MM-DD format.
effectiveTo	string	No	format: date	When this name stopped being used in YYYY-MM-DD format.

Responses

200 OK

Alias updated successfully.

DTO: PatientAliasResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}

Field	Type	Nullable	Description
id	Long	No	Alias record ID.
type	String	No	Type of name alias.
alias	String	Yes	Alias or nickname.
firstName	String	Yes	Alternate first name.
lastName	String	Yes	Alternate last name.
fullName	String	Yes	Full alternate name.
effectiveFrom	LocalDate	Yes	When this name was in use.
effectiveTo	LocalDate	Yes	When this name stopped being used.

400 Bad Request

Invalid request. Possible causes: Missing required field (type), No name field provided (alias, firstName, lastName, or fullName), Invalid type value, Invalid date format for effectiveFrom or effectiveTo, effectiveTo is before effectiveFrom

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or alias not found.

Example

curl -X PUT "https://demo.1health.io/api/v3/patient/1001/alias/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

PATCH/v3/patient/{patientId}/alias/{aliasId}

Partially update a patient name alias

Overview

Updates only the fields provided in the request body. Fields not included are left unchanged. Only non-null fields are applied. Existing values for omitted fields are preserved. Requires authentication. Returns 404 if the alias 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.
aliasId	Long	Yes	The ID of the alias record to partially update.

Request Body

Content-Type: application/json · DTO: PatientAliasRequestDTO

{
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "example-value",
  "effectiveTo": "example-value"
}

Field	Type	Required	Constraints	Description
type	string	Yes	allowableValues: maiden, nickname, preferred, previous, legal_change, alias	Type of name alias.
alias	string	No		Alias or nickname.
firstName	string	No		Alternate first name.
lastName	string	No		Alternate last name.
fullName	string	No		Full alternate name for mononyms or cultural formats.
effectiveFrom	string	No	format: date	When this name was in use in YYYY-MM-DD format.
effectiveTo	string	No	format: date	When this name stopped being used in YYYY-MM-DD format.

Responses

200 OK

Alias partially updated successfully.

DTO: PatientAliasResponseDTO

{
  "id": 1001,
  "type": "example-value",
  "alias": "example-value",
  "firstName": "example-value",
  "lastName": "example-value",
  "fullName": "example-value",
  "effectiveFrom": "2024-01-15",
  "effectiveTo": "2024-01-15"
}

Field	Type	Nullable	Description
id	Long	No	Alias record ID.
type	String	No	Type of name alias.
alias	String	Yes	Alias or nickname.
firstName	String	Yes	Alternate first name.
lastName	String	Yes	Alternate last name.
fullName	String	Yes	Full alternate name.
effectiveFrom	LocalDate	Yes	When this name was in use.
effectiveTo	LocalDate	Yes	When this name stopped being used.

400 Bad Request

Invalid request. Possible causes: Invalid type value, Invalid date format for effectiveFrom or effectiveTo, effectiveTo is before effectiveFrom

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or alias not found.

Example

curl -X PATCH "https://demo.1health.io/api/v3/patient/1001/alias/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type": "example-value", "alias": "example-value", "firstName": "example-value", "lastName": "example-value", "fullName": "example-value", "effectiveFrom": "example-value", "effectiveTo": "example-value"}'

DELETE/v3/patient/{patientId}/alias/{aliasId}

Deactivate a patient name alias

Overview

Soft-deletes an alias record. The alias is deactivated but preserved for audit trail. Requires authentication. Returns 404 if the alias 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.
aliasId	Long	Yes	The ID of the alias record to deactivate.

Responses

200 OK

Alias deactivated successfully.

DTO: PatientAliasDeleteResponseDTO

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

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

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Patient or alias not found.

Example

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

Alias

Endpoints

GET/v3/patient/{patientId}/alias

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

POST/v3/patient/{patientId}/alias

Overview

Authorization

Path Parameters

Request Body

Responses

201 Created

400 Bad Request

401 Unauthorized

404 Not Found

Example

GET/v3/patient/{patientId}/alias/{aliasId}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

PUT/v3/patient/{patientId}/alias/{aliasId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

PATCH/v3/patient/{patientId}/alias/{aliasId}

Overview

Authorization

Path Parameters

Request Body

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Example

DELETE/v3/patient/{patientId}/alias/{aliasId}

Overview

Authorization

Path Parameters

Responses

200 OK

401 Unauthorized

404 Not Found

Example

Navigation