Certifyos UDF Schema API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer UDF Schema API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: UDF Schema
  description: Endpoints for managing UDF schemas.
paths:
  /udf-schemas/entity-type/{entityType}:
    get:
      summary: Retrieve UDF schema for an entity type
      description: '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.'
      operationId: udfSchemaFindLatestByEntityType
      tags:
      - UDF Schema
      parameters:
      - description: 'The entity type for which to retrieve the UDF schema.


          Valid values:

          - `practitioner` - For practitioner entities

          - `facility` - For facility entities

          - `location` - For location entities

          - `group` - For group entities


          The value is case-insensitive.

          '
        example: practitioner
        in: path
        required: true
        name: entityType
        schema:
          type: string
          pattern: \S
      - description: 'Optional version number of the UDF schema to retrieve.

          If not provided, returns the latest version of the schema for the specified entity type.

          '
        example: 1
        in: query
        required: false
        name: version
        schema:
          type: integer
          format: int32
      - description: 'The tenant ID (organization ID) for which to retrieve the UDF schema.


          This header is required and identifies the tenant/organization context.

          The user must be a member of this organization to access its UDF schemas.

          '
        example: tenant-abc-123
        in: header
        required: true
        name: tenant-id
        schema:
          type: string
      responses:
        '200':
          description: '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.

            '
          content:
            application/json:
              example:
                id: udf-schema-7f3a9c21
                tenantId: tenant-abc-123
                entityType: practitioner
                schema: {}
                version: 1
                createdAt: '2026-05-14'
                createdBy: user-abc-123
                updatedAt: '2026-06-02'
                updatedBy: user-xyz-789
              schema:
                $ref: '#/components/schemas/UdfSchemaResponse'
        '400':
          description: '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

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 400
                  reason: INVALID_ENTITY_TYPE
                  title: Invalid entity type
                  detail: Entity type cannot be null or empty
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Unauthorized - Authentication required.


            The request lacks valid authentication credentials. Include a valid JWT Bearer token in the

            `Authorization` header and retry.

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 401
                  reason: UNAUTHORIZED
                  title: Authentication required
                  detail: Missing or invalid JWT Bearer token
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: '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.

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 403
                  reason: Forbidden
                  title: Request Failed
                  detail: An error occurred processing your request
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: '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

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 404
                  reason: NOT_FOUND
                  title: UDF schema not found
                  detail: No UDF schema found for entity type 'practitioner'
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: '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.

            '
          content:
            application/json:
              example:
                error: An unexpected error occurred
        '502':
          description: '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.

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 502
                  reason: DOWNSTREAM_SERVICE_ERROR
                  title: Downstream service unavailable
                  detail: Downstream service encountered an error
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: 'Service Unavailable - The downstream UDF schema service is temporarily unavailable, often due to

            network connectivity issues. Retry the request after a short delay.

            '
          content:
            application/json:
              example:
                errors:
                - httpStatus: 503
                  reason: SERVICE_UNAVAILABLE
                  title: Service unavailable
                  detail: The UDF schema service is temporarily unavailable
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - jwt: []
components:
  schemas:
    ApiError:
      type: object
      description: Standard API error response containing a list of error objects
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: List of error objects describing validation or processing failures
    Date:
      type: string
      format: date
    ErrorObject:
      type: object
      description: Individual error object containing details about a specific validation or processing error
      properties:
        httpStatus:
          type: integer
          format: int32
          examples:
          - 400
          description: HTTP status code for this error
        reason:
          type: string
          examples:
          - VALIDATION_ERROR
          description: Error reason/code
        title:
          type: string
          examples:
          - 'Validation failed for field: eventTypes'
          description: Error title/summary
        detail:
          type: string
          examples:
          - eventTypes is required and cannot be empty or null
          description: Detailed error message
        rejectedValue:
          type: string
          description: The value that was rejected, omitted for sensitive fields such as SSN
    JsonNodeType:
      type: string
      enum:
      - ARRAY
      - BINARY
      - BOOLEAN
      - MISSING
      - 'NULL'
      - NUMBER
      - OBJECT
      - POJO
      - STRING
    UdfSchemaResponse:
      type: object
      properties:
        id:
          type: string
        tenantId:
          type: string
        entityType:
          $ref: '#/components/schemas/EntityType'
        schema:
          $ref: '#/components/schemas/JsonNode'
        version:
          type: integer
          format: int32
        createdAt:
          $ref: '#/components/schemas/Date'
        createdBy:
          type: string
        updatedAt:
          $ref: '#/components/schemas/Date'
        updatedBy:
          type: string
    JsonNode:
      type: object
      properties:
        empty:
          type: boolean
        valueNode:
          type: boolean
        containerNode:
          type: boolean
        missingNode:
          type: boolean
        array:
          type: boolean
        object:
          type: boolean
        nodeType:
          $ref: '#/components/schemas/JsonNodeType'
        pojo:
          type: boolean
        number:
          type: boolean
        integralNumber:
          type: boolean
        floatingPointNumber:
          type: boolean
        short:
          type: boolean
        int:
          type: boolean
        long:
          type: boolean
        float:
          type: boolean
        double:
          type: boolean
        bigDecimal:
          type: boolean
        bigInteger:
          type: boolean
        textual:
          type: boolean
        boolean:
          type: boolean
        'null':
          type: boolean
        binary:
          type: boolean
    EntityType:
      type: string
      enum:
      - 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
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)