---
title: "Retrieve UDF schema for an entity type"
method: GET
path: "/udf-schemas/entity-type/{entityType}"
tags: ["UDF Schema"]
---

# Retrieve UDF schema for an entity type

`GET /udf-schemas/entity-type/{entityType}`

Returns the User Defined Fields (UDF) schema for the specified entity type within a tenant's
context. A UDF schema defines the structure and validation rules for the custom fields that can be
attached to entities such as practitioners.

**When to use:** Call this endpoint to discover what custom fields exist for a given entity type
before reading or writing UDF field values on a record. This endpoint returns the schema definition
only; it does not return the UDF field values stored on any specific record.

**Preconditions:**
- A valid JWT Bearer token must be present in the `Authorization` header.
- The caller must hold the `READ_UDF_SCHEMA` permission for the target tenant.
- The `tenant-id` header must identify a tenant of which the authenticated user is a member.
- A UDF schema for the requested entity type must have been provisioned for the tenant; otherwise a
  404 is returned.

**What you get back:** A `UdfSchemaResponse` object containing the entity type, tenant context,
version number, and a `schema` property — a JSON document that describes the custom fields defined
for the entity type. When `version` is omitted, the latest version is returned; when `version` is
supplied, that specific version is returned.

**Side effects:** None. This is a read-only operation.

**Supported entity types:** `practitioner` is confirmed supported. The `entityType` parameter also
accepts `facility`, `location`, and `group`; the availability of a provisioned schema for those
types depends on tenant configuration.

## Path parameters

- `entityType` string, required

## Query parameters

- `version` integer

## Headers

- `tenant-id` string, required

## Response `200`

The UDF schema for the requested entity type, including its version, tenant context, and the
`schema` document describing the custom fields. Reflects the latest version, or the specific
version requested via the `version` query parameter.

- UdfSchemaResponse
  - `id` string
  - `tenantId` string
  - `entityType` 'practitioner' | 'facility' | 'location' | 'group' | 'group_location' | 'group_practitioner_location' | 'tenant_group' | 'tenant_group_practitioners' | 'tenant_facility_location' | 'tenant_group_facility' | 'tenant_group_facility_location' | 'tenant_group_practitioner_network' | 'tenant_group_location_practitioner_network' | 'tenant_group_location' | 'tenant_group_network' | 'tenant_group_facility_network' | 'tenant_group_location_facility_network'
  - `schema` JsonNode
    - `empty` boolean
    - `valueNode` boolean
    - `containerNode` boolean
    - `missingNode` boolean
    - `array` boolean
    - `object` boolean
    - `nodeType` 'ARRAY' | 'BINARY' | 'BOOLEAN' | 'MISSING' | 'NULL' | 'NUMBER' | 'OBJECT' | 'POJO' | 'STRING'
    - `pojo` boolean
    - `number` boolean
    - `integralNumber` boolean
    - `floatingPointNumber` boolean
    - `short` boolean
    - `int` boolean
    - `long` boolean
    - `float` boolean
    - `double` boolean
    - `bigDecimal` boolean
    - `bigInteger` boolean
    - `textual` boolean
    - `boolean` boolean
    - `null` boolean
    - `binary` boolean
  - `version` integer
  - `createdAt` string, date
  - `createdBy` string
  - `updatedAt` string, date
  - `updatedBy` string

## Other responses

- `400` — Bad Request - Invalid request parameters or validation error. Common causes: - Entity type is null or empty - Invalid entity type value (must be one of: practitioner, facility, location, group) - Invalid tenant-id header
- `401` — Unauthorized - Authentication required. The request lacks valid authentication credentials. Include a valid JWT Bearer token in the `Authorization` header and retry.
- `403` — Forbidden - Insufficient permissions. The authenticated user does not have the required `READ_UDF_SCHEMA` permission for the specified tenant, or the user is not a member of the organization (tenant). Request the permission or use a tenant the caller belongs to.
- `404` — Not Found - UDF schema not found for the specified entity type. No UDF schema exists for the given entity type within the tenant's context. This may occur if: - The entity type has not been configured with a UDF schema - The schema was deleted or never created
- `500` — Internal Server Error - An unexpected server-side error prevented the request from completing. Note: errors originating from the downstream UDF schema service (DAL) with a 5xx status are remapped to `502 Bad Gateway`, not `500`, and are documented separately below. A genuine `500` returns a bare, unstructured body rather than the structured `ApiError` shape used elsewhere. Retry the request; if the error persists, contact support with the request details.
- `502` — Bad Gateway - The downstream UDF schema service returned a 5xx error. This is typically transient; retry the request after a short delay. The `detail` is a static, sanitized message and does not vary with the downstream failure.
- `503` — Service Unavailable - The downstream UDF schema service is temporarily unavailable, often due to network connectivity issues. Retry the request after a short delay.

---

[API](https://skmtc.dev/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.dev/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)