Certifyos Roster upload API

openapi: 3.2.0
info:
  title: Certifyos Roster upload API
  version: 1.0.0
  description: 'Operations tagged Roster upload across 2 of this provider''s published API definitions: certifyos-api-service-openapi.yml, certifyos-roster-service-openapi.yml. Each path carries the servers of the definition it was published in.'
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
- url: http://localhost:9001
  description: Local Development Server
tags:
- name: Roster upload
  description: APIs for roster upload file column mappings
paths:
  /roster-upload/{templateId}/column-mapping:
    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
    post:
      summary: Get mappings for the upload in a given template
      description: Get mappings details for the uploaded columns in a given template. Requires the column_mapping_enabled feature flag to be enabled. Uses tenant-specific schema paths from tenant_configurations if configured, otherwise falls back to default schemas.
      operationId: getMappingsForTheUploadInAGivenTemplate
      tags:
      - Roster upload
      parameters:
      - description: Template ID to fetch
        required: true
        name: templateId
        in: path
        schema:
          type: string
      - description: Tenant identifier
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUploadMappingsRequest'
        required: true
      responses:
        '200':
          description: Mapping details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUploadMappingsResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - Column mapping feature is disabled or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
      security:
      - jwt: []
  /roster-upload/{templateId}/column-mapping/template:
    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
    post:
      summary: create template from column mappings
      description: Creates a new template from the provided column mappings. Requires the column_mapping_enabled feature flag to be enabled. The mappings are validated against tenant-specific schemas if configured.
      operationId: createTemplateFromMappings
      tags:
      - Roster upload
      parameters:
      - description: Template ID to fetch
        required: true
        name: templateId
        in: path
        schema:
          type: string
      - description: Tenant identifier
        required: true
        name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveMappingsRequest'
        required: true
      responses:
        '200':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleStepTemplateFlowResponse'
        '400':
          description: Invalid input or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - Column mapping feature is disabled or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
      security:
      - jwt: []
components:
  schemas:
    SaveMappingsRequest:
      type: object
      properties:
        updateExistingTemplate:
          type: boolean
        jobType:
          $ref: '#/components/schemas/RosterJobType'
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        templateName:
          type: string
        templateDescription:
          type: string
    RosterJobType:
      type: string
      enum:
      - PRACTITIONER
      - FACILITY
    SingleStepTemplateFlowResponse:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        status:
          type: string
        templateId:
          type: string
        templateUrl:
          type: string
        schemaUrl:
          type: string
    Field:
      type: object
      properties:
        name:
          type: string
        mappedKey:
          type: string
        mappedEntity:
          type: string
        entityGroup:
          type: string
        isRequired:
          type: boolean
        isStaticField:
          type: boolean
        isSingleSelect:
          type: boolean
        validationRegex:
          type: string
        description:
          type: string
        enum:
          type: array
          items:
            type: string
        singleSelect:
          type: boolean
    GetUploadMappingsRequest:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        jobType:
          $ref: '#/components/schemas/RosterJobType'
        compareAgainstTemplate:
          type: boolean
    GetUploadMappingsResponse:
      type: object
      properties:
        mapped:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        unMapped:
          type: array
          items:
            type: string
        systemFields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
    ApiError:
      description: Standard API error response containing a list of error objects
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: List of error objects describing validation or processing failures
    ErrorObject:
      type: object
      description: Individual error object containing details about a specific validation or processing error
      properties:
        httpStatus:
          type: integer
          format: int32
          description: HTTP status code for this error
          examples:
          - 400
        reason:
          type: string
          description: Error reason/code
          examples:
          - VALIDATION_ERROR
        title:
          type: string
          description: Error title/summary
          examples:
          - 'Validation failed for field: eventTypes'
        detail:
          type: string
          description: Detailed error message
          examples:
          - eventTypes is required and cannot be empty or null
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- certifyos-api-service-openapi.yml
- certifyos-roster-service-openapi.yml