Custom Fields / Instance / Field
/v3/custom-data/instance/{boInstanceId}/field/{fieldKey} endpoint reference.
URL: https://demo.1health.io/api/v3/custom-data/instance/{boInstanceId}/field
APIs for reading and writing custom field values on business object instances. The tenant and application are resolved from the authenticated context.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /v3/custom-data/instance/{boInstanceId}/field/{fieldKey} | GET | Read a custom field value by key |
| /v3/custom-data/instance/{boInstanceId}/field/{fieldKey} | DELETE | Clear a custom field value by key |
GET/v3/custom-data/instance/{boInstanceId}/field/{fieldKey}
Read a custom field value by key
Overview
Overview: Returns the value of a single custom field on a business object instance, addressed by the field's key, or a null value when the field is unset.
Important Notes:
- Requires authentication; the target application is taken from the authenticated application context or from an explicit
appId(see theappIdparameter) - The field key is matched case-insensitively and must belong to the instance's business object class
Authorization
Bearer JWT required. See the authentication guide.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| boInstanceId | Long | Yes | The business object instance ID. |
| fieldKey | String | Yes | The custom field key (case-insensitive). |
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. The custom data field definitions belong to the application's owner tenant; the owner and any tenant the application is visible to (public, or explicitly allowed for a private application) may read and write values, which are stored against the caller's own instances. A request with neither an application context nor an explicit appId is rejected. |
Responses
200 Value retrieved successfully.
DTO: CustomDataResponseDTO
{
"fieldDefinitionId": 1001,
"fieldKey": "example-value",
"fieldType": "example-value",
"value": {}
}
| Field | Type | Nullable | Description |
|---|---|---|---|
| fieldDefinitionId | Long | Yes | ID of the custom field (custom data field definition). |
| fieldKey | String | Yes | System-generated camelCase key of the custom field. |
| fieldType | String | Yes | The attribute type of the custom field. One of: INTEGER, DECIMAL, TEXT, DATE, TIMESTAMP, JSON. |
| value | Object | Yes | The stored value, typed according to the field's fieldType. Null when the field has no value on this instance. |
401 Not authenticated — valid session required.
404 Field or instance not found.
Example
curl -X GET "https://demo.1health.io/api/v3/custom-data/instance/1001/field/example-value" \
-H "Authorization: Bearer $TOKEN"
DELETE/v3/custom-data/instance/{boInstanceId}/field/{fieldKey}
Clear a custom field value by key
Overview
Overview: Clears the value of a single custom field on a business object instance (sets the slot to null), addressed by the field's key. Other custom values on the instance are unaffected.
Important Notes:
- Requires authentication; the target application is taken from the authenticated application context or from an explicit
appId(see theappIdparameter) - The field key is matched case-insensitively and must belong to the instance's business object class
Authorization
Bearer JWT required. See the authentication guide.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| boInstanceId | Long | Yes | The business object instance ID. |
| fieldKey | String | Yes | The custom field key (case-insensitive). |
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. The custom data field definitions belong to the application's owner tenant; the owner and any tenant the application is visible to (public, or explicitly allowed for a private application) may read and write values, which are stored against the caller's own instances. A request with neither an application context nor an explicit appId is rejected. |
Responses
200 Value cleared successfully.
DTO: CustomDataResponseDTO
{
"fieldDefinitionId": 1001,
"fieldKey": "example-value",
"fieldType": "example-value",
"value": {}
}
| Field | Type | Nullable | Description |
|---|---|---|---|
| fieldDefinitionId | Long | Yes | ID of the custom field (custom data field definition). |
| fieldKey | String | Yes | System-generated camelCase key of the custom field. |
| fieldType | String | Yes | The attribute type of the custom field. One of: INTEGER, DECIMAL, TEXT, DATE, TIMESTAMP, JSON. |
| value | Object | Yes | The stored value, typed according to the field's fieldType. Null when the field has no value on this instance. |
401 Not authenticated — valid session required.
404 Field or instance not found.
Example
curl -X DELETE "https://demo.1health.io/api/v3/custom-data/instance/1001/field/example-value" \
-H "Authorization: Bearer $TOKEN"
Navigation
Parent: https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/agents.md · Site guide: https://agents.1health.io/public/demo/api/agents.md