---
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}"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/agents.md"
kind: "endpoints"
methods: [GET, PATCH]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/custom-data/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/custom-data/instance/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

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

REST API for reading and writing custom field values on business object instances.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/custom-data/instance/{boInstanceId} | GET | Read all custom field values for an instance |
| /v3/custom-data/instance/{boInstanceId} | PATCH | Create, update, or clear custom field values |

---

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

Read all custom field values for an instance

### Overview

Returns all custom field values set on a business object instance as a flat JSON object keyed by custom field key, within the authenticated tenant and application context.

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

### 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 Values retrieved successfully.

```json
{}
```

#### 401 Not authenticated — valid session required.

#### 404 Instance not found.

### Example

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

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

Create, update, or clear custom field values

### Overview

Writes one or more custom field values on a business object instance in a single request. The body is a flat JSON object keyed by custom field key; each value is validated against its field definition, and only the referenced fields are written.

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

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

```json
{}
```

### Responses

#### 200 Values upserted successfully.

```json
{}
```

#### 400 Invalid request. Possible causes: • A value is not valid for its field's type or JSON schema • An empty body was provided • Missing external application context

#### 401 Not authenticated — valid session required.

#### 404 A referenced field or the instance was not found.

### Example

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

---

## Child Routes

| Path | Methods | Summary | agents.md |
| --- | --- | --- | --- |
| /v3/custom-data/instance/{boInstanceId} | — | field | https://agents.1health.io/public/demo/api/v3/custom-data/instance/_boInstanceId_/agents.md |

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