/api/contact:
  get:
    tags: [Contact]
    summary: List contacts
    security:
      - bearerAuth: []
    parameters:
      - name: ContactName
        in: query
        schema:
          type: string
        description: Filter by contact name (searches in NameFirst and NameLast)
      - name: Specialty
        in: query
        schema:
          type: string
        description: Filter by medical specialty code
    responses:
      '200':
        description: List of contacts
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  type: array
                  items:
                    $ref: '../components/schemas/master-data.yaml#/Contact'

  post:
    tags: [Contact]
    summary: Create new contact
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - NameFirst
            properties:
              NameFirst:
                type: string
                description: First name
              NameLast:
                type: string
                description: Last name
              Title:
                type: string
                description: Title (e.g., Dr, Mr, Mrs)
              Initial:
                type: string
                description: Middle initial
              Birthdate:
                type: string
                format: date-time
                description: Date of birth
              EmailAddress1:
                type: string
                format: email
                description: Primary email address
              EmailAddress2:
                type: string
                format: email
                description: Secondary email address
              Phone:
                type: string
                description: Primary phone number
              MobilePhone1:
                type: string
                description: Primary mobile number
              MobilePhone2:
                type: string
                description: Secondary mobile number
              Specialty:
                type: string
                description: Medical specialty code
              SubSpecialty:
                type: string
                description: Sub-specialty code
    responses:
      '201':
        description: Contact created successfully
        content:
          application/json:
            schema:
              $ref: '../components/schemas/common.yaml#/SuccessResponse'
      '422':
        description: Validation error
        content:
          application/json:
            schema:
              $ref: '../components/schemas/common.yaml#/ErrorResponse'


  delete:
    tags: [Contact]
    summary: Delete contact
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - ContactID
            properties:
              ContactID:
                type: integer
                description: Contact ID to delete
    responses:
      '200':
        description: Contact deleted successfully
        content:
          application/json:
            schema:
              $ref: '../components/schemas/common.yaml#/SuccessResponse'

/api/contact/{id}:
  get:
    tags: [Contact]
    summary: Get contact by ID
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Contact ID
    responses:
      '200':
        description: Contact details
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                message:
                  type: string
                data:
                  $ref: '../components/schemas/master-data.yaml#/Contact'

  patch:
    tags: [Contact]
    summary: Update contact
    security:
      - bearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Contact ID to update
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - NameFirst
            properties:
              NameFirst:
                type: string
                description: First name
              NameLast:
                type: string
                description: Last name
              Title:
                type: string
                description: Title (e.g., Dr, Mr, Mrs)
              Initial:
                type: string
                description: Middle initial
              Birthdate:
                type: string
                format: date-time
                description: Date of birth
              EmailAddress1:
                type: string
                format: email
                description: Primary email address
              EmailAddress2:
                type: string
                format: email
                description: Secondary email address
              Phone:
                type: string
                description: Primary phone number
              MobilePhone1:
                type: string
                description: Primary mobile number
              MobilePhone2:
                type: string
                description: Secondary mobile number
              Specialty:
                type: string
                description: Medical specialty code
              SubSpecialty:
                type: string
                description: Sub-specialty code
              Details:
                description: |
                  Detail payload supports either a flat array of new rows (legacy format)
                  or an operations object with `created`, `edited`, and `deleted` arrays.
                oneOf:
                  - $ref: '../components/schemas/master-data.yaml#/ContactDetailOperations'
                  - type: array
                    description: Legacy format for replacing details with new rows only
                    items:
                      $ref: '../components/schemas/master-data.yaml#/ContactDetail'
    responses:
      '201':
        description: Contact updated successfully
        content:
          application/json:
            schema:
              $ref: '../components/schemas/common.yaml#/SuccessResponse'
      '422':
        description: Validation error
        content:
          application/json:
            schema:
              $ref: '../components/schemas/common.yaml#/ErrorResponse'
