openapi: 3.1.0
info:
  title: FeedbackPulse REST API
  version: v1
  summary: Employee API
  description: A workspace Admin creates API keys in Settings > Integrations > API Clients. This contract covers listing, reading, creating, and syncing employees.
  license:
    name: Proprietary
    url: https://feedbackpulse.com/terms
servers:
  - url: https://api.feedbackpulse.com
    description: Canonical production API host
security:
  - BearerAuth: []
tags:
  - name: Employees
    description: Employee resource endpoints
  - name: Employee Sync
    description: Synchronous employee sync command endpoint
paths:
  /v1/employees:
    get:
      tags:
        - Employees
      operationId: listEmployees
      summary: List employees
      security:
        - BearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number to return, starting at 1.
        - in: query
          name: per_page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Number of employees per page.
      responses:
        "200":
          description: Paginated employee list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeCollectionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-required-scope: employees:read
    post:
      tags:
        - Employees
      operationId: createEmployee
      summary: Create an employee
      description: Creates a single employee resource within the API client's tenant.
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmployeeWriteRequest"
      responses:
        "201":
          description: Employee created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/IdempotencyConflict"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-required-scope: employees:write
  /v1/employees/{employee}:
    get:
      tags:
        - Employees
      operationId: getEmployee
      summary: Get an employee
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmployeeId"
      responses:
        "200":
          description: Employee found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-required-scope: employees:read
  /v1/employees/sync:
    post:
      tags:
        - Employee Sync
      operationId: syncEmployees
      summary: Sync employees
      description: |
        Synchronously creates or updates employees from a canonical batch payload.
        The response contains per-row actions, warnings, and summarized totals.

        A row that would terminate the last active admin of the workspace is not applied. It is
        reported as `errored` with the code `last_active_admin` in `errors`, and the request
        still answers 200. A batch that terminates every admin therefore keeps one of them active.
        A refused row is stored with the rest of the response: a retry with the same Idempotency-Key
        replays it even after another admin exists, so retry with a new key.
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmployeeSyncRequest"
      responses:
        "200":
          description: Sync completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmployeeSyncResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/IdempotencyConflict"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-required-scope: employees:sync
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Tenant-owned FeedbackPulse API client key.
  parameters:
    EmployeeId:
      in: path
      name: employee
      required: true
      schema:
        type: string
      description: |
        Canonical public employee identifier, for example `emp_01H...`.
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: |
        Replays the original response when the same API client sends the same key and
        same request fingerprint to the same POST route. Rate-limited (429) and server
        error (5xx) responses are not stored, so retry them with the same key. A key whose
        request never finished returns 409 `idempotency_key_in_progress` for 10 minutes;
        after that, the next request with the same key and payload runs again.
  responses:
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
          example:
            message: Unauthenticated.
    Forbidden:
      description: Authenticated but lacking the required API client scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    NotFound:
      description: Resource not found in the API client's tenant scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NotFoundError"
    UnprocessableEntity:
      description: Validation failed or the idempotency key is invalid
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/ValidationError"
              - $ref: "#/components/schemas/ApiError"
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    IdempotencyConflict:
      description: Idempotency key reused with a different request payload or still in progress
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
          examples:
            conflict:
              value:
                error: idempotency_key_conflict
                error_description: This Idempotency-Key was already used with a different request payload.
            in_progress:
              value:
                error: idempotency_key_in_progress
                error_description: A request with this Idempotency-Key is already being processed.
  schemas:
    ManagerSummary:
      type:
        - object
        - "null"
      properties:
        id:
          type: string
          description: Canonical public employee identifier, for example `emp_01H...`.
        name:
          type: string
    Employee:
      type: object
      required:
        - id
        - name
        - email
        - employment_status
        - account_status
        - access_status
        - is_manager
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Canonical public employee identifier, for example `emp_01H...`.
        name:
          type: string
        email:
          type: string
          format: email
        job_title:
          type:
            - string
            - "null"
        department:
          type:
            - string
            - "null"
        employee_number:
          type:
            - string
            - "null"
        type:
          type:
            - string
            - "null"
        employment_status:
          type: string
          enum:
            - active
            - terminated
        account_status:
          type:
            - string
            - "null"
          enum:
            - not-invited
            - invited
            - active
            - null
          description: Null means activation history is unknown for a legacy terminated employee.
        access_status:
          type: string
          enum:
            - enabled
            - disabled
        is_manager:
          type: boolean
        hire_date:
          type:
            - string
            - "null"
          format: date
        termination_date:
          type:
            - string
            - "null"
          format: date
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        manager:
          $ref: "#/components/schemas/ManagerSummary"
    EmployeeResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/Employee"
        meta:
          type: object
          properties:
            warnings:
              type: array
              items:
                type: string
    EmployeeCollectionResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Employee"
        meta:
          type: object
          properties:
            current_page:
              type: integer
            from:
              type:
                - integer
                - "null"
            last_page:
              type: integer
            path:
              type: string
            per_page:
              type: integer
            to:
              type:
                - integer
                - "null"
            total:
              type: integer
        links:
          type: object
          additionalProperties: true
    EmployeeWriteRequest:
      type: object
      required:
        - name
        - email
        - type
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        job_title:
          type:
            - string
            - "null"
        department:
          type:
            - string
            - "null"
        employee_number:
          type:
            - string
            - "null"
        type:
          type: string
          enum:
            - full-time
            - part-time
            - contractor
        employment_status:
          type: string
          enum:
            - active
            - terminated
          description: Rehire changes employment only. Access requires explicit admin reinstatement.
        hire_date:
          type:
            - string
            - "null"
          format: date
        termination_date:
          type:
            - string
            - "null"
          format: date
        is_manager:
          type: boolean
        manager_id:
          type:
            - string
            - "null"
          description: |
            Canonical public employee identifier for the manager, for example
            `emp_01H...`. Internal numeric ids are rejected.
        send_invitation:
          type: boolean
    EmployeeSyncRequest:
      type: object
      allOf:
        - if:
            properties:
              employees:
                contains:
                  type: object
                  anyOf:
                    - required:
                        - external_id
                      properties:
                        external_id: &a1
                          type: string
                          pattern: \S
                    - properties:
                        manager:
                          type: object
                          required:
                            - external_id
                          properties:
                            external_id: *a1
                      required:
                        - manager
          then:
            required:
              - source
            properties:
              source: *a1
      required:
        - employees
      properties:
        source:
          type:
            - string
            - "null"
          description: Required when any employee row or manager reference uses `external_id`.
        employees:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object
            required:
              - email
            properties:
              external_id:
                type:
                  - string
                  - "null"
              email:
                type: string
                format: email
              name:
                type:
                  - string
                  - "null"
              employee_number:
                type:
                  - string
                  - "null"
              job_title:
                type:
                  - string
                  - "null"
              department:
                type:
                  - string
                  - "null"
              type:
                type: string
                enum:
                  - full-time
                  - part-time
                  - contractor
              employment_status:
                type: string
                enum:
                  - active
                  - terminated
                description: |
                  Rehire never restores access or sends invitations. `terminated` is reported as an
                  `errored` row with the code `last_active_admin` for the last active admin.
              send_invitation:
                type: boolean
                default: false
                description: Explicit invitation command, rejected while access is disabled or account is activated.
              hire_date:
                type:
                  - string
                  - "null"
                format: date
              termination_date:
                type:
                  - string
                  - "null"
                format: date
              is_manager:
                type: boolean
              manager:
                oneOf:
                  - type: "null"
                  - anyOf:
                      - type: object
                        required:
                          - external_id
                        properties:
                          external_id:
                            type:
                              - string
                              - "null"
                          email:
                            type:
                              - string
                              - "null"
                            format: email
                      - type: object
                        required:
                          - email
                        properties:
                          external_id:
                            type:
                              - string
                              - "null"
                          email:
                            type:
                              - string
                              - "null"
                            format: email
    EmployeeSyncResponse:
      type: object
      required:
        - summary
        - results
        - errors
      properties:
        summary:
          type: object
          required:
            - total
            - created
            - updated
            - skipped
            - errored
          properties:
            total:
              type: integer
            created:
              type: integer
            updated:
              type: integer
            skipped:
              type: integer
            errored:
              type: integer
        results:
          type: array
          items:
            type: object
            required:
              - row
              - action
              - email
              - warnings
            properties:
              row:
                type: integer
              action:
                type: string
                enum:
                  - created
                  - updated
                  - skipped
                  - errored
              employee_id:
                type:
                  - string
                  - "null"
              email:
                type: string
                format: email
              warnings:
                type: array
                items:
                  type: string
        errors:
          type: array
          items:
            type: object
            required:
              - row
              - code
              - message
            properties:
              row:
                type: integer
              code:
                type: string
                description: Machine-readable row error code, for example `last_active_admin`.
              message:
                type: string
    ApiError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        required_scope:
          type: string
      examples:
        - error: invalid_idempotency_key
          error_description: Idempotency-Key must be a non-empty string up to 255 characters.
    NotFoundError:
      type: object
      properties:
        message:
          type: string
    ValidationError:
      type: object
      required:
        - message
        - errors
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
