Pleo Employees API

openapi: 3.0.1
info:
  title: App Marketplace accounting-entries Employees API
  description: API for Pleo App Marketplace
  termsOfService: https://pleo.io/terms/
  contact:
    email: partner-ecosystem-team@pleo.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 39.4.0
servers:
- url: https://external.pleo.io
  description: Production server
- url: https://external.staging.pleo.io
  description: Staging server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Employees
  description: "The Employees API enables you to search for employee records that\nare managed in Pleo. You can perform the following: \n - Search for multiple\nemployees \n - Search for a specific employee record by employee ID"
paths:
  /v2/employees:
    get:
      tags:
      - Employees
      summary: Search for employees
      description: Use this endpoint to search for multiple employees.
      operationId: Search Employees
      parameters:
      - name: companyId
        in: query
        description: Enter the company ID of the employees you are searching for. This is not a mandatory parameter; hence, if you do not know the company ID, the response message contains details of all employees to which you have access. If you are searching for employees at the organisation level, ensure that the access token used for authentication has the correct permissions.
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: uuid
      - name: email
        in: query
        description: The email of the Employee you are searching for.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: code
        in: query
        description: The external ID of the Employee you are searching for.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: before
        in: query
        description: Lower bound of the page of data to return (cannot be used together with [after] or [offset]).
        required: false
        style: form
        explode: true
        schema:
          pattern: ^[A-Z2-7=~]+$
          type: string
      - name: after
        in: query
        description: Upper bound of the page of data to return (cannot be used together with [before] or [offset]).
        required: false
        style: form
        explode: true
        schema:
          pattern: ^[A-Z2-7=~]+$
          type: string
      - name: offset
        in: query
        description: Offset of the page of data to return (cannot be used together with [before] or [after]).
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: The maximum amount of items to return.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: sorting_keys
        in: query
        description: The keys to sort the results by.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sorting_order
        in: query
        description: The order to sort the results by. Must be the same length as [sortingKeys]; one order per key.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PageOrder'
      responses:
        '200':
          description: Employee search successful
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponseExternalEmployeeResponseModel'
        '403':
          description: 'Forbidden: User lacks the necessary permissions'
  /v2/employees/{employeeId}:
    get:
      tags:
      - Employees
      summary: Search for a specific employee
      description: Search for a specific employee by employee ID.
      operationId: Get employee by ID
      parameters:
      - name: employeeId
        in: path
        description: Enter the employee ID.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Employee resource found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DataResponseExternalEmployeeResponseModel'
        '403':
          description: 'Forbidden: User lacks the necessary permissions to access this Employee'
        '404':
          description: 'Not Found: Employee with given ID not found'
components:
  schemas:
    CursorPaginatedResponseExternalEmployeeResponseModel:
      required:
      - data
      - pagination
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExternalEmployeeResponseModel'
        pagination:
          $ref: '#/components/schemas/CursorPageInfo'
    CursorPageInfo:
      required:
      - currentRequestPagination
      - hasNextPage
      - hasPreviousPage
      type: object
      properties:
        currentRequestPagination:
          $ref: '#/components/schemas/CursorPageCurrentRequestInfo'
        endCursor:
          type: string
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
        total:
          type: integer
          format: int64
    ExternalEmployeeResponseModel:
      required:
      - companyId
      - email
      - firstName
      - id
      - lastName
      type: object
      properties:
        code:
          type: string
          description: External ID of the Employee
        companyId:
          type: string
          description: Company ID of the Employee
          format: uuid
        email:
          type: string
          description: Email of the Employee
        firstName:
          type: string
          description: First name of the Employee
        id:
          type: string
          description: ID of the Employee
          format: uuid
        jobTitle:
          type: string
          description: Job title of the Employee
        lastName:
          type: string
          description: Last name of the Employee
        phone:
          type: string
          description: Phone number of the Employee
    DataResponseExternalEmployeeResponseModel:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ExternalEmployeeResponseModel'
    CursorPageCurrentRequestInfo:
      required:
      - parameters
      type: object
      properties:
        after:
          type: string
        before:
          type: string
        limit:
          type: integer
          format: int32
        offset:
          type: integer
          format: int64
        parameters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        sortingKeys:
          type: array
          items:
            type: string
        sortingOrder:
          type: array
          items:
            $ref: '#/components/schemas/PageOrder'
    PageOrder:
      type: string
      enum:
      - ASC
      - ASC_NULLS_FIRST
      - ASC_NULLS_LAST
      - DESC
      - DESC_NULLS_FIRST
      - DESC_NULLS_LAST
  securitySchemes:
    bearerAuth:
      type: http
      description: 'JWT Bearer token authentication. Include the token in the Authorization header as: `Bearer <token>`'
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      description: Basic HTTP authentication using API key. Use your API key as the username and leave the password empty. The credentials will be Base64 encoded automatically.
      scheme: basic