---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/custom-data/instance/{boInstanceId}/field/{fieldKey}"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/field/agents.md"
kind: "endpoints"
methods: [GET, DELETE]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/field/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/field/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/field/use-case.md"
source_version: "43d07c0335624b7661c2872315a5f184e8c3d832"
extractor_model: "gpt-4o-2024-08-06"
extractor_prompt_version: "2026-08-13.v1"
reconciler_model: "claude-sonnet-4-6"
reconciler_prompt_version: "2026-08-13.v1"
generated_at: "2026-08-27T01:13:03.949984+00:00"
---

# /v3/custom-data/instance/{boInstanceId}/field

**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 the `appId` parameter)
- 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](https://agents.1health.io/public/demo/api/authentication/agents.md).

### 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`

```json
{
  "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

```bash
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 the `appId` parameter)
- 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](https://agents.1health.io/public/demo/api/authentication/agents.md).

### 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`

```json
{
  "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

```bash
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