Patient Vault v3 API

URL: https://demo.1health.io/api/v3/custom-data/definition

APIs for defining custom fields on a business object class. Supports creating, replacing, partially updating, and retiring definitions. The tenant and application are resolved from the authenticated context; storage slots are allocated automatically.

Endpoints

---

GET/v3/custom-data/definition

List all custom data definitions for an application

Overview

Returns all custom data definitions defined for the resolved application, across every business object class, within the authenticated tenant and application context.

Authorization

Bearer JWT required. See the authentication guide.

Query Parameters

Responses

200 OK

Custom data definitions retrieved successfully.

DTO: Page

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

400 Bad Request

Invalid request. Missing external application context.

401 Unauthorized

Not authenticated — valid session required.

Example

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

POST/v3/custom-data/definition

Create a custom data definition

Overview

Defines a custom data definition on a business object class together with its fields. The caller provides a definition name, the target boClassId, and the list of fields (each a business displayName and fieldType); the platform automatically allocates the next available storage slot for each field.

Authorization

Bearer JWT required. See the authentication guide.

Query Parameters

Request Body

Content-Type: application/json · DTO: CustomDataDefinitionRequestDTO

{
  "name": "example-value",
  "boClassId": "example-value",
  "fields": "example-value"
}

Responses

201 Created

Custom field definition created successfully.

DTO: CustomDataDefinitionResponseDTO

{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}

400 Bad Request

Invalid request. Possible causes: • Missing required field (name, boClassId, fields, or a field's displayName/fieldType) • boClassId does not reference an existing business object class • Unsupported fieldType • Duplicate displayName within the business object class • No storage slots remain for an attribute type • Invalid jsonSchema • Missing external application context

401 Unauthorized

Not authenticated — valid session required.

Example

curl -X POST "https://demo.1health.io/api/v3/custom-data/definition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name": "example-value", "boClassId": "example-value", "fields": "example-value"}'

GET/v3/custom-data/definition/{id}

Retrieve a custom data definition by ID

Overview

Returns a single custom data definition with its fields by its ID, within the authenticated tenant and application context.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Query Parameters

Responses

200 OK

Custom data definition retrieved successfully.

DTO: CustomDataDefinitionResponseDTO

{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}

400 Bad Request

Invalid request. Missing external application context.

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Custom data definition not found.

Example

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

PUT/v3/custom-data/definition/{id}

Replace a custom data definition

Overview

Replaces the mutable properties of an existing custom data definition. Only the definition name may be changed; its fields are managed separately.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Query Parameters

Request Body

Content-Type: application/json · DTO: CustomDataDefinitionUpdateRequestDTO

{
  "name": "example-value"
}

Responses

200 OK

Custom data definition replaced successfully.

DTO: CustomDataDefinitionResponseDTO

{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}

400 Bad Request

Invalid request. Missing required field (name).

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Custom data definition not found.

Example

curl -X PUT "https://demo.1health.io/api/v3/custom-data/definition/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name": "example-value"}'

PATCH/v3/custom-data/definition/{id}

Partially update a custom data definition

Overview

Updates only the mutable properties provided in the request body. Properties not included are left unchanged.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Query Parameters

Request Body

Content-Type: application/json · DTO: CustomDataDefinitionUpdateRequestDTO

{
  "name": "example-value"
}

Responses

200 OK

Custom data definition updated successfully.

DTO: CustomDataDefinitionResponseDTO

{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Custom data definition not found.

Example

curl -X PATCH "https://demo.1health.io/api/v3/custom-data/definition/1001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name": "example-value"}'

DELETE/v3/custom-data/definition/{id}

Retire a custom data definition

Overview

Soft-deletes a custom data definition together with all of its fields. The definition and its fields are hidden from default queries but preserved for audit.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Query Parameters

Responses

200 OK

Custom data definition retired successfully.

DTO: CustomDataDefinitionDeleteResponseDTO

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

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Custom data definition not found.

Example

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

---

Child Routes

Navigation

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