openapi: 3.0.0
info:
  title: OrgPerson
  version: 2.0.0
  description: >
    An **OrgPerson** represents the assignment of a person to an organization
    unit,

    optionally with a role in the organization chart.


    Use this API to:

    - Assign a person to an organization unit with an optional role

    - Find all people in an organization unit (filter by `org_unit_id`)

    - Find all organization units a person belongs to (filter by `person_id`)

    - Find all people with a specific organizational role (filter by
    `org_role_id`)


    Supports historicization.
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/org-person/index:
    post:
      summary: index
      operationId: indexOrgPerson
      tags:
        - OrgPersons
      description: |
        Returns a paginated list of person-unit assignments.

        Most useful filters:
        - `org_unit_id`: all people in a specific organization unit
        - `person_id`: all units a person belongs to
        - `org_role_id`: all people with a specific organizational role
      requestBody:
        description: Parameters for searching
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgPersonIndexParams"
            example:
              filter:
                org_unit_id: 6d7e8f90-1234-5678-abcd-ef6789012345
              per-page: 20
              page: 1
              sort: person_last_name
      responses:
        "200":
          description: List of person-unit assignments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewOrgPerson"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/org-person/create:
    post:
      summary: create
      operationId: createOrgPerson
      tags:
        - OrgPersons
      description: |
        Assigns a person to an organization unit.

        Requires `person_id` and `org_unit_id`.
        The `org_person_id` is auto-generated if not provided.

        Optionally pass `org_role_id` to assign a specific organizational role.
        If omitted, the person is assigned to the unit without a specific role.
      requestBody:
        description: Assignment to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgPerson"
      responses:
        "201":
          description: Person assigned successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgPerson"
  /v2/org-person/view/{id}:
    get:
      summary: view
      operationId: viewOrgPerson
      tags:
        - OrgPersons
      description: Retrieves a single assignment by its ID.
      parameters:
        - name: id
          in: path
          description: The org_person_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Assignment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewOrgPerson"
        "404":
          description: Not found
  /v2/org-person/update/{id}:
    put:
      summary: update
      operationId: updateOrgPerson
      tags:
        - OrgPersons
      description: Updates an existing assignment.
      parameters:
        - name: id
          in: path
          description: The org_person_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgPerson"
      responses:
        "200":
          description: Updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgPerson"
        "404":
          description: Not found
  /v2/org-person/delete/{id}:
    delete:
      summary: delete
      operationId: deleteOrgPerson
      tags:
        - OrgPersons
      description: Deletes a person-unit assignment.
      parameters:
        - name: id
          in: path
          description: The org_person_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the assignment.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    OrgPerson:
      type: object
      required:
        - org_unit_id
        - person_id
      properties:
        org_person_id:
          type: string
          format: uuid
          description: Unique identifier. Auto-generated if not provided.
        org_unit_id:
          type: string
          format: uuid
          description: The organization unit. Pass the `org_unit_id` from the OrgUnit API.
        person_id:
          type: string
          format: uuid
          description: The person. Pass the `person_id` from the Person API.
        org_role_id:
          type: string
          format: uuid
          nullable: true
          description: The organizational role (optional). Pass the `org_role_id` from the
            OrgRole API. If omitted, the person is assigned without a specific
            role.
    ViewOrgPerson:
      type: object
      properties:
        org_person_id:
          type: string
          format: uuid
        org_unit_id:
          type: string
          format: uuid
        person_id:
          type: string
          format: uuid
        org_role_id:
          type: string
          format: uuid
          nullable: true
        org_unit_code:
          type: string
          description: Code of the organization unit.
        org_unit_name:
          type: string
          description: Name of the organization unit.
        org_role_code:
          type: string
          nullable: true
          description: Code of the organizational role.
        org_role_name:
          type: string
          nullable: true
          description: Name of the organizational role.
        person_first_name:
          type: string
        person_last_name:
          type: string
        person_code:
          type: string
        person_is_employee:
          type: boolean
        project_name:
          type: string
          description: Name of the project.
        owned_active:
          type: boolean
          nullable: true
          description: Whether this assignment is currently active.
        parent_active:
          type: boolean
          nullable: true
          description: Whether the parent entities are currently active.
    OrgPersonIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewOrgPerson"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - person_first_name
            - person_last_name
            - person_code
            - org_unit_name
            - org_role_name
        history:
          type: boolean
          description: If true, includes historicized entries.
      example:
        filter:
          org_unit_id: 6d7e8f90-1234-5678-abcd-ef6789012345
        per-page: 100
        page: 1
        sort: person_last_name
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
