Patient Vault — 1health

Custom Fields / Definition / Field

/v3/custom-data/definition/{id}/field endpoint reference.

URL: https://demo.1health.io/api/v3/custom-data/definition/{id}/field

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

Endpoint	Method	Description
/v3/custom-data/definition/{id}/field	POST	Add a custom field to a definition

POST/v3/custom-data/definition/{id}/field

Add a custom field to a definition

Overview

Overview: Adds a single custom field to an existing custom data definition. The caller provides a business displayName and fieldType; the platform automatically allocates the next available storage slot for the field's attribute type.

Behavior & Use Cases:

The fieldType must be one of the supported attribute types, matched case-insensitively: INTEGER (alias INT), DECIMAL, TEXT, DATE, TIMESTAMP, JSON (alias JSONB); unsupported types are rejected
The lowest available storage slot for the attribute type is allocated automatically; each definition supports up to 20 fields per attribute type, except JSON which supports up to 3
The request is rejected when no slots remain for the selected attribute type
The displayName must be unique within the definition
When fieldType is JSON, a provided jsonSchema must be well-formed JSON

Important Notes:

Requires authentication; the target application is taken from the authenticated application context or from an explicit appId (see the appId parameter)
Returns 404 when the definition does not exist for the caller's application

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Parameter	Type	Required	Description
id	Long	Yes	The ID of the custom data definition to add the field to.

Query Parameters

Parameter	Type	Required	Default	Description
appId	Long	No		External application the custom data belongs to. Optional; when omitted, the application is resolved from the authenticated context. Custom data definitions belong to the application's owner tenant: creating, updating or deleting them requires being a system administrator of that owner tenant, while reading them is allowed for the owner and any tenant the application is visible to (public, or explicitly allowed for a private application). A request with neither an application context nor an explicit appId is rejected.

Request Body

Content-Type: application/json · DTO: CustomDataFieldDefinitionRequestDTO

{
  "displayName": "example-value",
  "fieldType": "example-value",
  "jsonSchema": "example-value"
}

Field	Type	Required	Constraints	Description
displayName	string	Yes	Must be unique within the business object class for the caller's application.	Display name of the custom field.
fieldType	string	Yes	Matched case-insensitively. Accepted values: INTEGER (alias INT), DECIMAL, TEXT, DATE, TIMESTAMP, JSON (alias JSONB).	The attribute type of the custom field.
jsonSchema	string	No	Only applicable when fieldType is JSON; ignored for other types. Must be well-formed JSON when provided.	JSON schema used to validate values of this field.

Responses

201 Created

Custom field added successfully.

DTO: CustomDataFieldDefinitionViewDTO

{
  "id": 1001,
  "name": "example-value",
  "displayName": "example-value",
  "fieldKey": "example-value",
  "fieldType": "example-value",
  "jsonSchema": "example-value"
}

Field	Type	Nullable	Description
id	Long	No	Custom field instance ID.
name	String	No	Sanitized bo-core name of the custom field, derived from the display name with special characters removed. Read-only; it cannot be set through the create/update APIs.
displayName	String	No	Display name of the custom field.
fieldKey	String	No	System-generated camelCase key derived from the field's name, used for programmatic lookup and search. Read-only; it cannot be set through the create/update APIs.
fieldType	String	No	The attribute type of the custom field. One of: INTEGER, DECIMAL, TEXT, DATE, TIMESTAMP, JSON.
jsonSchema	String	Yes	JSON schema used to validate values of this field, when applicable.

400 Bad Request

Invalid request. Possible causes: • Missing required displayName or fieldType • Unsupported fieldType • Duplicate displayName within the definition • No storage slots remain for the attribute type • Invalid jsonSchema • Missing external application context

401 Unauthorized

Not authenticated — valid session required.

404 Not Found

Custom data definition not found.

Example

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

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

Patient Vault v3 API