---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/custom-data/definition"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/custom-data/definition/agents.md"
kind: "endpoints"
methods: [GET, POST, 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/definition/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/custom-data/definition/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/custom-data/definition/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/definition

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

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/definition | GET | List all custom data definitions for an application |
| /v3/custom-data/definition | POST | Create a custom data definition |
| /v3/custom-data/definition/{id} | GET | Retrieve a custom data definition by ID |
| /v3/custom-data/definition/{id} | PUT | Replace a custom data definition |
| /v3/custom-data/definition/{id} | PATCH | Partially update a custom data definition |
| /v3/custom-data/definition/{id} | DELETE | Retire a custom data definition |

---

## GET /v3/custom-data/definition

List all custom data definitions for an application

### Overview

Returns all custom data definitions defined for the resolved application, across every business object class, 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).

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| includeFields | boolean | No | false | When true, each definition is returned together with its fields; when false only the definition metadata is returned. Defaults to false. |
| name | String | No |  | Optional filter that restricts the result to definitions whose name matches the given value case-insensitively (exact match, not a substring). |
| appId | Long | No |  | External application the custom data belongs to. Optional; when omitted, the application is resolved from the authenticated context. |
| page | int | No | 0 | Zero-based page number. |
| size | int | No | 50 | Page size. |

### Responses

#### 200 OK

Custom data definitions retrieved successfully.

**DTO**: `Page`

```json
{
  "data": [
    {}
  ],
  "pageNumber": 1,
  "pageSize": 1,
  "offset": 1001,
  "emptyPage": true,
  "firstPage": true,
  "lastPage": true,
  "numberOfElements": 1001,
  "totalElements": 1001,
  "totalPages": 1
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| data | List<CustomDataDefinitionResponseDTO> | No |  |
| pageNumber | int | No |  |
| pageSize | int | No |  |
| offset | long | No |  |
| emptyPage | boolean | No |  |
| firstPage | boolean | No |  |
| lastPage | boolean | No |  |
| numberOfElements | long | No |  |
| totalElements | long | No |  |
| totalPages | int | No |  |

### Example

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

## POST /v3/custom-data/definition

Create a custom data definition

### Overview

Defines a custom data definition on a business object class together with its fields. The caller provides a definition name, the target boClassId, and the list of fields (each a business displayName and fieldType); the platform automatically allocates the next available storage slot for each field.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### 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**: `CustomDataDefinitionRequestDTO`

```json
{
  "name": "example-value",
  "boClassId": "example-value",
  "fields": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| name | string | Yes |  | Human-readable name of the custom data definition. |
| boClassId | integer | Yes |  | ID of the business object class the custom data definition is attached to. |
| fields | array | Yes |  | The custom fields that make up this definition. |

### Responses

#### 201 Created

Custom field definition created successfully.

**DTO**: `CustomDataDefinitionResponseDTO`

```json
{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Custom data definition instance ID. |
| name | String | Yes | Human-readable name of the custom data definition. |
| boClassId | Long | Yes | ID of the business object class the custom data definition is attached to. |
| typeKey | String | Yes | Key of the business object class the custom data definition is attached to. |
| appId | Long | Yes | Owning application. |
| fields | List<CustomDataFieldDefinitionViewDTO> | Yes | The custom fields that make up this definition. |

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/custom-data/definition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"name": "example-value", "boClassId": "example-value", "fields": "example-value"}'
```

## GET /v3/custom-data/definition/{id}

Retrieve a custom data definition by ID

### Overview

Returns a single custom data definition with its fields by its ID, 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 |
| --- | --- | --- | --- |
| id | Long | Yes | The ID of the custom data definition to retrieve. |

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

**DTO**: `CustomDataDefinitionResponseDTO`

```json
{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Custom data definition instance ID. |
| name | String | Yes | Human-readable name of the custom data definition. |
| boClassId | Long | Yes | ID of the business object class the custom data definition is attached to. |
| typeKey | String | Yes | Key of the business object class the custom data definition is attached to. |
| appId | Long | Yes | Owning application. |
| fields | List<CustomDataFieldDefinitionViewDTO> | Yes | The custom fields that make up this definition. |

### Example

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

## PUT /v3/custom-data/definition/{id}

Replace a custom data definition

### Overview

Replaces the mutable properties of an existing custom data definition. Only the definition name may be changed; its fields are managed separately.

### 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 data definition 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**: `CustomDataDefinitionUpdateRequestDTO`

```json
{
  "name": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| name | string | Yes |  | New human-readable name of the custom data definition. Required for a full replace (PUT); optional for a partial update (PATCH), where an omitted value leaves the name unchanged. |

### Responses

#### 200 OK

Custom data definition replaced successfully.

**DTO**: `CustomDataDefinitionResponseDTO`

```json
{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Custom data definition instance ID. |
| name | String | Yes | Human-readable name of the custom data definition. |
| boClassId | Long | Yes | ID of the business object class the custom data definition is attached to. |
| typeKey | String | Yes | Key of the business object class the custom data definition is attached to. |
| appId | Long | Yes | Owning application. |
| fields | List<CustomDataFieldDefinitionViewDTO> | Yes | The custom fields that make up this definition. |

### Example

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

## PATCH /v3/custom-data/definition/{id}

Partially update a custom data definition

### Overview

Updates only the mutable properties provided 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 data definition 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**: `CustomDataDefinitionUpdateRequestDTO`

```json
{
  "name": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| name | string | No |  | New human-readable name of the custom data definition. Required for a full replace (PUT); optional for a partial update (PATCH), where an omitted value leaves the name unchanged. |

### Responses

#### 200 OK

Custom data definition updated successfully.

**DTO**: `CustomDataDefinitionResponseDTO`

```json
{
  "id": 1001,
  "name": "example-value",
  "boClassId": 1001,
  "typeKey": "example-value",
  "appId": 1001,
  "fields": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | Yes | Custom data definition instance ID. |
| name | String | Yes | Human-readable name of the custom data definition. |
| boClassId | Long | Yes | ID of the business object class the custom data definition is attached to. |
| typeKey | String | Yes | Key of the business object class the custom data definition is attached to. |
| appId | Long | Yes | Owning application. |
| fields | List<CustomDataFieldDefinitionViewDTO> | Yes | The custom fields that make up this definition. |

### Example

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

## DELETE /v3/custom-data/definition/{id}

Retire a custom data definition

### Overview

Soft-deletes a custom data definition together with all of its fields. The definition and its fields are hidden from default queries but preserved for audit.

### 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 data definition to retire. |

### 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 data definition retired 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. |

### Example

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

---

## Child Routes

| Path | Methods | Summary | agents.md |
| --- | --- | --- | --- |
| /v3/custom-data/definition/type | GET |  | https://agents.1health.io/public/demo/api/v3/custom-data/definition/type/agents.md |
| /v3/custom-data/definition/{id} | — | field | https://agents.1health.io/public/demo/api/v3/custom-data/definition/_id_/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