Custom Fields / Field
/v3/custom-data/field/{id} endpoint reference.
URL: https://demo.1health.io/api/v3/custom-data/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/field/{id} | PUT | Replace a custom field |
| /v3/custom-data/field/{id} | PATCH | Partially update a custom field |
| /v3/custom-data/field/{id} | DELETE | Delete a custom field |
PUT/v3/custom-data/field/{id}
Replace a custom field
Overview
Replaces the mutable properties of a single custom field within a definition. The field displayName is updated, and for a JSON field its jsonSchema may also be replaced. The field's type and physical storage slot are immutable.
Authorization
Bearer JWT required. See the authentication guide.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | Long | Yes | The ID of the custom field to replace. |
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. |
Request Body
Content-Type: application/json · DTO: CustomDataFieldDefinitionUpdateRequestDTO
{
"displayName": "example-value",
"jsonSchema": "example-value"
}
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| displayName | string | Yes | Must remain unique within the business object class for the caller's application. | New display name of the custom field. |
| jsonSchema | string | No | Must be well-formed JSON when provided. | JSON schema used to validate values of this field. Only applies when the field's type is JSON. |
Responses
200 OK
Custom field replaced 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. |
| 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. |
| fieldType | String | No | The attribute type of the custom field. |
| jsonSchema | String | Yes | JSON schema used to validate values of this field, when applicable. |
400 Bad Request
Invalid request. Possible causes: Missing required displayName, Duplicate displayName within the business object class, Invalid jsonSchema, Missing external application context.
401 Unauthorized
Not authenticated — valid session required.
404 Not Found
Custom field not found.
Example
curl -X PUT "https://demo.1health.io/api/v3/custom-data/field/1001" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"displayName": "example-value", "jsonSchema": "example-value"}'
PATCH/v3/custom-data/field/{id}
Partially update a custom field
Overview
Updates only the mutable properties of a single custom field that are present in the request body. Properties not included are left unchanged.
Authorization
Bearer JWT required. See the authentication guide.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | Long | Yes | The ID of the custom field to partially update. |
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. |
Request Body
Content-Type: application/json · DTO: CustomDataFieldDefinitionUpdateRequestDTO
{
"displayName": "example-value",
"jsonSchema": "example-value"
}
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| displayName | string | No | Must remain unique within the business object class for the caller's application. | New display name of the custom field. |
| jsonSchema | string | No | Must be well-formed JSON when provided. | JSON schema used to validate values of this field. Only applies when the field's type is JSON. |
Responses
200 OK
Custom field updated 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. |
| 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. |
| fieldType | String | No | The attribute type of the custom field. |
| jsonSchema | String | Yes | JSON schema used to validate values of this field, when applicable. |
400 Bad Request
Invalid request. Possible causes: Duplicate displayName within the business object class, Invalid jsonSchema, Missing external application context.
401 Unauthorized
Not authenticated — valid session required.
404 Not Found
Custom field not found.
Example
curl -X PATCH "https://demo.1health.io/api/v3/custom-data/field/1001" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"displayName": "example-value", "jsonSchema": "example-value"}'
DELETE/v3/custom-data/field/{id}
Delete a custom field
Overview
Soft-deletes a single custom field within a definition. The definition itself and its other fields are left intact.
Authorization
Bearer JWT required. See the authentication guide.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | Long | Yes | The ID of the custom field to delete. |
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. |
Responses
200 OK
Custom field deleted successfully.
DTO: CustomDataDefinitionDeleteResponseDTO
{
"id": 1001,
"active": true,
"deletedAt": "example-value"
}
| Field | Type | Nullable | Description |
|---|---|---|---|
| id | Long | No | The ID of the deleted custom field definition. |
| active | boolean | No | Whether the definition is still active. |
| deletedAt | string | No | Timestamp when the definition was deleted, in ISO-8601 format. |
401 Unauthorized
Not authenticated — valid session required.
404 Not Found
Custom field not found.
Example
curl -X DELETE "https://demo.1health.io/api/v3/custom-data/field/1001" \
-H "Authorization: Bearer $TOKEN"
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