openapi: 3.0.0
info:
  title: Pave External API
  description: Documentation for the Pave External API
  version: '1.0'
paths:
  /ping:
    get:
      operationId: PingController_ping
      parameters: []
      responses:
        '200':
          description: Returns "pong" message on success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponseDto'
              example:
                message: pong
      summary: Test Endpoint
      tags:
        - Ping API
  /v1/compensationPlanning/meritCycles:
    get:
      description: Returns a list of all merit cycles
      operationId: MeritCycleController_findAll_v1
      parameters:
        - name: status
          required: false
          in: query
          description: The status of the merit cycle
          schema:
            enum:
              - active
              - inactive
              - finalized
            type: string
        - name: startDate
          required: false
          in: query
          description: The start date of the merit cycle
          schema:
            properties:
              gt:
                description: Greater than the start date
                type: string
                format: YYYY-MM-DD
                example: '2025-01-15'
              gte:
                description: Greater than or equal to the start date
                type: string
                format: YYYY-MM-DD
                example: '2025-01-15'
              lt:
                description: Less than the start date
                type: string
                format: YYYY-MM-DD
                example: '2025-01-15'
              lte:
                description: Less than or equal to the start date
                type: string
                format: YYYY-MM-DD
                example: '2025-01-15'
            type: object
        - name: limit
          required: false
          in: query
          description: The number of merit cycles to return
          schema:
            maximum: 100
            default: 25
            type: number
        - name: nextCursor
          required: false
          in: query
          description: The next cursor to paginate through the list of merit cycles
          schema:
            example: >-
              eyJleHRlcm5hbF9pZCI6Im1jZV8wNDdiZTg0ZC02OGQxLTRiMzYtYmU0Mi0xY2RlMTE4MjdhZTkifQ==
            type: string
      responses:
        '200':
          description: Returns a list of merit cycles on success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponseDto'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/MeritCycleResponseDto'
              example:
                data:
                  - id: mc_12345678-1234-5678-9012-123456789012
                    name: H1 Merit Cycle
                    startDate: '2025-01-01T00:00:00.000Z'
                    endDate: '2025-01-31T00:00:00.000Z'
                    createdDate: '2024-06-17T18:55:43.000Z'
                    status: active
      summary: List Merit Cycles
      tags:
        - Merit Cycle API
  /v1/compensationPlanning/meritCycles/{id}:
    get:
      description: Returns a single Merit Cycle by ID
      operationId: MeritCycleController_findById_v1
      parameters:
        - name: id
          required: true
          in: path
          description: The ID of the Merit Cycle
          schema:
            type: string
      responses:
        '200':
          description: Returns a Merit Cycle on success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeritCycleResponseDto'
              example:
                id: mc_12345678-1234-5678-9012-123456789012
                name: H1 Merit Cycle
                startDate: '2025-01-01T00:00:00.000Z'
                endDate: '2025-01-31T00:00:00.000Z'
                createdDate: '2024-06-17T18:55:43.000Z'
                status: active
      summary: Get a Merit Cycle by ID
      tags:
        - Merit Cycle API
  /v1/compensationPlanning/meritCycles/{meritCycleId}/employees:
    get:
      description: Returns a list of all merit cycle employees
      operationId: MeritCycleEmployeeController_findAll_v1
      parameters:
        - name: meritCycleId
          required: true
          in: path
          description: The ID of the Merit Cycle
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: The number of merit cycle employees to return
          schema:
            maximum: 100
            default: 25
            type: number
        - name: nextCursor
          required: false
          in: query
          description: >-
            The next cursor to paginate through the list of merit cycle
            employees
          schema:
            example: >-
              eyJleHRlcm5hbF9pZCI6Im1jZV8wNDdiZTg0ZC02OGQxLTRiMzYtYmU0Mi0xY2RlMTE4MjdhZTkifQ==
            type: string
      responses:
        '200':
          description: Returns a list of merit cycle employees on success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponseDto'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/MeritCycleEmployeeResponseDto'
              example:
                data:
                  - id: mce_2312c64b-h5f1-46ca-8607-661a66319b91
                    email: pave.smith@pave.com
                    firstName: Pave
                    lastName: Smith
                    preferredName: null
                    currencyCode: USD
                    eligibilityStatus: eligible
                    columns:
                      department:
                        type: text
                        name: Department
                        value: Sales Operations
                      employee:
                        type: composite
                        name: Employee
                        value:
                          fullName: Pave Smith
                          jobLevel: P4
                          jobTitle: Sales Operations Manager
                nextCursor: >-
                  eyJleHRlcm5hbF9pZCI6Im1jZV8wNDdiZTg0ZC02OGQxLTRiMzYtYmU0Mi0xY2RlMTE4MjdhZTkifQ==
      summary: List Merit Cycle Employees
      tags:
        - Merit Cycle Employee API
components:
  schemas:
    PingResponseDto:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: pong
      required:
        - message
    PaginatedResponseDto:
      type: object
      properties:
        nextCursor:
          type: string
          description: The next cursor to use for pagination
          example: >-
            eyJleHRlcm5hbF9pZCI6Im1jZV8wNDdiZTg0ZC02OGQxLTRiMzYtYmU0Mi0xY2RlMTE4MjdhZTkifQ==
    MeritCycleResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The ID of the Merit Cycle
          example: mc_12345678-1234-5678-9012-123456789012
        name:
          type: string
          description: The name of the Merit Cycle
          example: H1 Merit Cycle
        startDate:
          format: date-time
          type: string
          description: The start date of the Merit Cycle
          example: '2025-01-01T00:00:00.000Z'
        endDate:
          format: date-time
          type: string
          description: The end date of the Merit Cycle
          example: '2025-01-31T00:00:00.000Z'
        createdDate:
          format: date-time
          type: string
          description: The date the Merit Cycle was created
          example: '2024-06-17T18:55:43.000Z'
        status:
          type: string
          description: The status of the Merit Cycle
          example: active
          enum:
            - active
            - inactive
            - finalized
      required:
        - id
        - name
        - startDate
        - endDate
        - createdDate
        - status
    MeritCycleEmployeeColumnResponseDto:
      type: object
      properties:
        name:
          type: string
          description: The name of the Merit Cycle Employee Column
        type:
          type: string
          description: >-
            The type of the Merit Cycle Employee Column (text, number, currency,
            boolean, composite)
        value:
          description: The value of the Merit Cycle Employee Column
          oneOf:
            - type: string
              example:
                text: Sales
            - type: boolean
              example:
                isPromotion: true
            - type: object
              description: Currency code value
              properties:
                code:
                  type: string
                  description: Currency Code according to ISO 4217
                value:
                  type: string
                  description: Readable Currency Name
              example:
                code: USD
                value: United States Dollar
            - type: object
              additionalProperties:
                oneOf:
                  - type: string
                  - type: number
                  - type: object
                    description: Currency code value
                    properties:
                      code:
                        type: string
                        description: Currency Code according to ISO 4217
                      value:
                        type: string
                        description: Readable Currency Name
              example:
                composite:
                  fullName: John Doe
                  jobLevel: P4
                  jobTitle: Sales Manager
      required:
        - name
        - type
        - value
    MeritCycleEmployeeResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The ID of the Merit Cycle Employee
          example: mce_2312c64b-h5f1-46ca-8607-661a66319b91
        email:
          type: string
          description: The email of the Merit Cycle Employee
          example: john.doe@example.com
        firstName:
          type: string
          description: The first name of the Merit Cycle Employee
          example: John
        lastName:
          type: string
          description: The last name of the Merit Cycle Employee
          example: Doe
        preferredName:
          type: object
          description: The preferred name (if any) of the Merit Cycle Employee
          example: John
          nullable: true
        currencyCode:
          type: object
          description: The currency code of the Merit Cycle Employee
          example:
            code: USD
            value: United States Dollar
          properties:
            code:
              type: string
              description: Currency Code according to ISO 4217
            value:
              type: string
              description: Readable Currency Name
        eligibilityStatus:
          type: string
          description: The eligibility status of the Merit Cycle Employee
          example: eligible
          enum:
            - eligible
            - ineligible
        columns:
          type: object
          description: The columns of the Merit Cycle Employee
          example:
            department:
              name: Department
              type: text
              value: Sales
            employee:
              name: Employee
              type: composite
              value:
                fullName: John Doe
                jobLevel: P4
                jobTitle: Sales Manager
          additionalProperties:
            $ref: '#/components/schemas/MeritCycleEmployeeColumnResponseDto'
      required:
        - id
        - email
        - firstName
        - lastName
        - preferredName
        - currencyCode
        - eligibilityStatus
        - columns
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key generated within the Pave App
servers:
  - url: https://api.pave.com
    description: Pave Production Server
tags: []
security:
  - api-key: []
