---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/custom-data/field/{id}"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/custom-data/field/agents.md"
kind: "endpoints"
methods: [PUT, PATCH, DELETE]
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/field/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/custom-data/field/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/custom-data/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/field

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

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

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

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

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

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

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

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

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

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

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

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