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.

Request

Responses

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.

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.