StackOne Employees API

openapi: 3.2.0
info:
  title: Marketing Accounts Employees API
  description: The documentation for the StackOne Unified API - MARKETING
  contact: {}
  version: 1.0.0
servers:
- url: https://api.stackone.com
tags:
- name: Employees
paths:
  /unified/hris/employees/{id}/time_off:
    get:
      tags:
      - Employees
      summary: List Employee Time Off Requests
      operationId: hris_list_employee_time_off_requests
      parameters:
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The page number of the results to fetch
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of results per page
        schema:
          type: string
          default: '25'
      - name: raw
        in: query
        description: Indicates that the raw request result is returned
        schema:
          type: boolean
          default: false
      - name: fields
        in: query
        description: The comma separated list of fields to return in the response (if empty, all fields are returned)
        schema:
          type: string
          default: ''
        example: id,employee_id,name,phone_number,street_1,street_2,city,state,zip_code,country,location_type,created_at,updated_at
      - name: sync_token
        in: query
        description: The sync token to select the only updated results
        schema:
          type: string
      - name: updated_after
        in: query
        description: Use a string with a date to only select results updated after that given date
        schema:
          type: string
        example: '2020-01-01T00:00:00.000Z'
      - name: proxy
        in: query
        description: Query parameters that can be used to pass through parameters to the underlying provider request by surrounding them with "proxy" key
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        example:
          proxy:
            custom_filter_param: '123'
            filter[eq][name]: Luke
      responses:
        '200':
          description: The time off requests related to the employee with the given identifier were retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffPaginated'
        '400':
          description: Invalid request.
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
        '501':
          description: This functionality is not implemented.
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: list_employee_time_off_requests
    post:
      tags:
      - Employees
      summary: Create Employee Time Off Request
      operationId: hris_create_employee_time_off_request
      parameters:
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HrisCreateTimeOffRequestDto'
        required: true
      responses:
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
        '501':
          description: This functionality is not implemented.
        '201':
          description: Record created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTimeOffResult'
        '400':
          description: Invalid request.
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: create_employee_time_off_request
  /unified/hris/employees/{id}/time_off/{subResourceId}:
    get:
      tags:
      - Employees
      summary: Get Employees Time Off Request
      operationId: hris_get_employees_time_off_request
      parameters:
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: subResourceId
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The page number of the results to fetch
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of results per page
        schema:
          type: string
          default: '25'
      - name: raw
        in: query
        description: Indicates that the raw request result is returned
        schema:
          type: boolean
          default: false
      - name: fields
        in: query
        description: The comma separated list of fields to return in the response (if empty, all fields are returned)
        schema:
          type: string
          default: ''
        example: id,employee_id,name,phone_number,street_1,street_2,city,state,zip_code,country,location_type,created_at,updated_at
      - name: sync_token
        in: query
        description: The sync token to select the only updated results
        schema:
          type: string
      - name: updated_after
        in: query
        description: Use a string with a date to only select results updated after that given date
        schema:
          type: string
        example: '2020-01-01T00:00:00.000Z'
      - name: proxy
        in: query
        description: Query parameters that can be used to pass through parameters to the underlying provider request by surrounding them with "proxy" key
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        example:
          proxy:
            custom_filter_param: '123'
            filter[eq][name]: Luke
      responses:
        '500':
          description: Server error while executing the request.
        '501':
          description: This functionality is not implemented.
        '200':
          description: The time off request related to the employee with the given identifiers was retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffResult'
        '400':
          description: Invalid request.
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: get_employees_time_off_request
  /unified/hris/employees/{id}:
    get:
      tags:
      - Employees
      summary: Get Employee
      operationId: hris_get_employee
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The page number of the results to fetch
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of results per page
        schema:
          type: string
          default: '25'
      - name: raw
        in: query
        description: Indicates that the raw request result is returned
        schema:
          type: boolean
          default: false
      - name: fields
        in: query
        description: The comma separated list of fields to return in the response (if empty, all fields are returned)
        schema:
          type: string
          default: ''
        example: id,first_name,last_name,name,display_name,gender,ethnicity,date_of_birth,birthday,marital_status,avatar_url,avatar,personal_email,personal_phone_number,work_email,work_phone_number,job_title,department,manager_id,hire_date,start_date,tenure,work_anniversary,employment_type,employment_contract_type,employment_status,termination_date,company_name,home_location,work_location,employments,custom_fields,created_at,updated_at
      - name: sync_token
        in: query
        description: The sync token to select the only updated results
        schema:
          type: string
      - name: updated_after
        in: query
        description: Use a string with a date to only select results updated after that given date
        schema:
          type: string
        example: '2020-01-01T00:00:00.000Z'
      - name: expand
        in: query
        description: The comma separated list of fields that will be expanded in the response
        schema:
          type: string
          default: ''
        example: company,employments,work_location,home_location,custom_fields
      - name: include
        in: query
        description: The comma separated list of fields that will be included in the response
        schema:
          type: string
          default: ''
        example: avatar_url,avatar,custom_fields
      - name: proxy
        in: query
        description: Query parameters that can be used to pass through parameters to the underlying provider request by surrounding them with "proxy" key
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        example:
          proxy:
            custom_filter_param: '123'
            filter[eq][name]: Luke
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      responses:
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
        '501':
          description: This functionality is not implemented.
        '200':
          description: The employee with the given identifier was retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResult'
        '400':
          description: Invalid request.
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: get_employee
    patch:
      tags:
      - Employees
      summary: Updates an employee
      operationId: hris_update_employee
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HrisCreateEmployeeRequestDto'
        required: true
      responses:
        '501':
          description: This functionality is not implemented.
        '200':
          description: Record updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmployeeResult'
        '400':
          description: Invalid request.
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: update_employee
  /unified/hris/employees:
    get:
      tags:
      - Employees
      summary: List Employees
      operationId: hris_list_employees
      parameters:
      - name: page
        in: query
        description: The page number of the results to fetch
        schema:
          type: string
      - name: page_size
        in: query
        description: The number of results per page
        schema:
          type: string
          default: '25'
      - name: raw
        in: query
        description: Indicates that the raw request result is returned
        schema:
          type: boolean
          default: false
      - name: fields
        in: query
        description: The comma separated list of fields to return in the response (if empty, all fields are returned)
        schema:
          type: string
          default: ''
        example: id,first_name,last_name,name,display_name,gender,ethnicity,date_of_birth,birthday,marital_status,avatar_url,avatar,personal_email,personal_phone_number,work_email,work_phone_number,job_title,department,manager_id,hire_date,start_date,tenure,work_anniversary,employment_type,employment_contract_type,employment_status,termination_date,company_name,home_location,work_location,employments,custom_fields,created_at,updated_at
      - name: sync_token
        in: query
        description: The sync token to select the only updated results
        schema:
          type: string
      - name: updated_after
        in: query
        description: Use a string with a date to only select results updated after that given date
        schema:
          type: string
        example: '2020-01-01T00:00:00.000Z'
      - name: expand
        in: query
        description: The comma separated list of fields that will be expanded in the response
        schema:
          type: string
          default: ''
        example: company,employments,work_location,home_location,custom_fields
      - name: include
        in: query
        description: The comma separated list of fields that will be included in the response
        schema:
          type: string
          default: ''
        example: avatar_url,avatar,custom_fields
      - name: proxy
        in: query
        description: Query parameters that can be used to pass through parameters to the underlying provider request by surrounding them with "proxy" key
        style: deepObject
        explode: true
        schema:
          type: object
          additionalProperties: true
        example:
          proxy:
            custom_filter_param: '123'
            filter[eq][name]: Luke
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      responses:
        '501':
          description: This functionality is not implemented.
        '200':
          description: The list of employees was retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeesPaginated'
        '400':
          description: Invalid request.
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
      security:
      - basic: []
      x-speakeasy-usage-example:
        title: List Employees
        position: 1
      x-speakeasy-group: hris
      x-speakeasy-name-override: list_employees
    post:
      tags:
      - Employees
      summary: Creates an employee
      operationId: hris_create_employee
      parameters:
      - name: x-account-id
        in: header
        description: The account identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HrisCreateEmployeeRequestDto'
        required: true
      responses:
        '403':
          description: Forbidden.
        '412':
          description: 'Precondition failed: linked account belongs to a disabled integration.'
        '429':
          description: Too many requests.
        '500':
          description: Server error while executing the request.
        '501':
          description: This functionality is not implemented.
        '201':
          description: The employee was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmployeeResult'
        '400':
          description: Invalid request.
      security:
      - basic: []
      x-speakeasy-group: hris
      x-speakeasy-name-override: create_employee
components:
  schemas:
    Employee:
      type: object
      properties:
        avatar_url:
          type: string
          description: The employee avatar Url
          example: https://example.com/avatar.png
        date_of_birth:
          type: string
          description: The employee date_of_birth
          example: '1990-01-01'
        manager_id:
          type: string
          description: The employee manager ID
          example: '67890'
        home_location:
          allOf:
          - $ref: '#/components/schemas/HRISLocation'
          description: The employee home location
        employment_status:
          allOf:
          - $ref: '#/components/schemas/EmploymentStatusEnum'
          description: The employee employment status
          example: active
        first_name:
          type: string
          description: The employee first name
          example: Issac
        work_phone_number:
          type: string
          description: The employee work phone number
          example: '+1234567890'
        termination_date:
          type: string
          description: The employee termination date
          example: '2023-06-14T00:00:00Z'
        avatar:
          allOf:
          - $ref: '#/components/schemas/Image'
          description: The employee avatar
          example: https://example.com/avatar.png
        job_title:
          type: string
          description: The employee job title
          example: Physicist
        employment_contract_type:
          allOf:
          - $ref: '#/components/schemas/EmploymentScheduleTypeEnum'
          description: The employment work schedule type (e.g., full-time, part-time)
          example: full_time
        work_location:
          allOf:
          - $ref: '#/components/schemas/HRISLocation'
          description: The employee work location
        tenure:
          type: string
          description: The employee tenure
          example: 2
        work_anniversary:
          type: string
          description: The employee work anniversary
          example: '2022-06-14T00:00:00Z'
        start_date:
          type: string
          description: The employee start date
          example: '2022-01-01'
        employments:
          type: array
          items:
            $ref: '#/components/schemas/Employment'
          description: The employee employments
        department:
          type: string
          description: The employee department
          example: Physics
        updated_at:
          type: string
          description: The updated_at date
          example: '2023-06-14T01:00:00Z'
        last_name:
          type: string
          description: The employee last name
          example: Newton
        marital_status:
          allOf:
          - $ref: '#/components/schemas/MaritalStatusEnum'
          description: The employee marital status
          example: single
        display_name:
          type: string
          description: The employee display name
          example: Sir Issac Newton
        company_name:
          type: string
          description: The employee company name
          example: Example Corp
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeCustomFields'
          description: The employee custom fields
        personal_email:
          type: string
          description: The employee personal email
          example: isaac.newton@example.com
        id:
          type: string
          description: The employee ID
          example: 1687-3
        work_email:
          type: string
          description: The employee work email
          example: newton@example.com
        name:
          type: string
          description: The employee name
          example: Issac Newton
        personal_phone_number:
          type: string
          description: The employee personal phone number
          example: '+1234567890'
        birthday:
          type: string
          description: The employee birthday
          example: '2023-06-14T00:00:00Z'
        employment_type:
          allOf:
          - $ref: '#/components/schemas/EmploymentTypeEnum'
          description: The employee employment type
          example: full_time
        hire_date:
          type: string
          description: The employee hire date
          example: '2022-01-01'
        ethnicity:
          allOf:
          - $ref: '#/components/schemas/EthnicityEnum'
          description: The employee ethnicity
          example: white
        created_at:
          type: string
          description: The created_at date
          example: '2023-06-14T01:00:00Z'
        gender:
          allOf:
          - $ref: '#/components/schemas/GenderEnum'
          description: The employee gender
          example: male
    HrisCreateEmployeeRequestDto:
      type: object
      properties:
        personal_email:
          type: string
          description: The employee personal email
          example: isaac.newton@example.com
        hire_date:
          type: string
          description: The employee hire date
          example: '2022-01-01'
        job_title:
          type: string
          description: The employee job title
          example: Physicist
        work_email:
          type: string
          description: The employee work email
          example: newton@example.com
        avatar:
          allOf:
          - $ref: '#/components/schemas/Image'
          description: The employee avatar
          example: https://example.com/avatar.png
        manager_id:
          type: string
          description: The employee manager ID
          example: '67890'
        start_date:
          type: string
          description: The employee start date
          example: '2022-01-01'
        ethnicity:
          allOf:
          - $ref: '#/components/schemas/EthnicityEnum'
          description: The employee ethnicity
          example: white
        employment_contract_type:
          allOf:
          - $ref: '#/components/schemas/EmploymentScheduleTypeEnum'
          description: The employment work schedule type (e.g., full-time, part-time)
          example: full_time
        employment_type:
          allOf:
          - $ref: '#/components/schemas/EmploymentTypeEnum'
          description: The employee employment type
          example: full_time
        work_location:
          allOf:
          - $ref: '#/components/schemas/HrisLocationsCreateRequestDto'
          description: The employee work location
        tenure:
          type: string
          description: The employee tenure
          example: 2
        first_name:
          type: string
          description: The employee first name
          example: Issac
        company_name:
          type: string
          description: The employee company name
          example: Example Corp
        employments:
          type: array
          items:
            $ref: '#/components/schemas/Employment'
          description: The employee employments
        work_phone_number:
          type: string
          description: The employee work phone number
          example: '+1234567890'
        department:
          type: string
          description: The employee department
          example: Physics
        avatar_url:
          type: string
          description: The employee avatar Url
          example: https://example.com/avatar.png
        birthday:
          type: string
          description: The employee birthday
          example: '2023-06-14T00:00:00Z'
        name:
          type: string
          description: The employee name
          example: Issac Newton
        employment_status:
          allOf:
          - $ref: '#/components/schemas/EmploymentStatusEnum'
          description: The employee employment status
          example: active
        gender:
          allOf:
          - $ref: '#/components/schemas/GenderEnum'
          description: The employee gender
          example: male
        home_location:
          allOf:
          - $ref: '#/components/schemas/HrisLocationsCreateRequestDto'
          description: The employee home location
        termination_date:
          type: string
          description: The employee termination date
          example: '2023-06-14T00:00:00Z'
        date_of_birth:
          type: string
          description: The employee date_of_birth
          example: '1990-01-01'
        personal_phone_number:
          type: string
          description: The employee personal phone number
          example: '+1234567890'
        display_name:
          type: string
          description: The employee display name
          example: Sir Issac Newton
        work_anniversary:
          type: string
          description: The employee work anniversary
          example: '2022-06-14T00:00:00Z'
        last_name:
          type: string
          description: The employee last name
          example: Newton
        marital_status:
          allOf:
          - $ref: '#/components/schemas/MaritalStatusEnum'
          description: The employee marital status
          example: single
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeCustomFields'
          description: The employee custom fields
    Image:
      type: object
      properties:
        base64:
          type: string
        url:
          type: string
    TimeOff:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the time off request
          example: '123456'
        start_date:
          type: string
          description: The start date of the time off request
        status:
          allOf:
          - $ref: '#/components/schemas/TimeOffStatusEnum'
          description: The status of the time off request
        updated_date:
          type: string
          description: The updated date of the time off request
        approver_id:
          type: string
          description: The approver ID
          example: 1687-4
        employee_id:
          type: string
          description: The employee ID
          example: 1687-3
        type:
          allOf:
          - $ref: '#/components/schemas/TimeOffTypeEnum'
          description: The type of the time off request
        end_date:
          type: string
          description: The end date of the time off request
        created_date:
          type: string
          description: The created date of the time off request
    CreateTimeOffResult:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        statusCode:
          type: number
        message:
          type: string
      required:
      - statusCode
      - message
      - timestamp
    EmployeeResult:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Employee'
        raw:
          type: string
      required:
      - data
    HRISLocation:
      type: object
      properties:
        zip_code:
          type: string
          description: The ZIP code/Postal code of the location
          example: NG33 5NR
        street_1:
          type: string
          description: The first line of the address
          example: Water Lane
        street_2:
          type: string
          description: The second line of the address
          example: Woolsthorpe by Colsterworth
        updated_at:
          type: string
          description: The updated_at date
          example: '2023-06-14T01:00:00Z'
        id:
          type: string
          description: The unique ID of the location
          example: '123456'
        phone_number:
          type: string
          description: The phone number of the location
          example: +44 1476 860 364
        employee_id:
          type: string
          description: The employee ID
          example: 1687-3
        city:
          type: string
          description: The city where the location is situated
          example: Grantham
        country:
          allOf:
          - $ref: '#/components/schemas/CountryCodeEnum'
          description: The country code
          example: GB
        name:
          type: string
          description: The name of the location
          example: Woolsthorpe Manor
        created_at:
          type: string
          description: The created_at date
          example: '2023-06-14T01:00:00Z'
        state:
          type: string
          description: The state where the location is situated
          example: Lincolnshire
        location_type:
          allOf:
          - $ref: '#/components/schemas/LocationTypeEnum'
          description: The location type
          example: work
    EthnicityEnum:
      type: object
      properties:
        source_value:
          type: string
        value:
          type: string
          enum:
          - white
          - black_or_african_american
          - asian
          - hispanic_or_latino
          - american_indian_or_alaska_native
          - native_hawaiian_or_pacific_islander
          - two_or_more_races
          - not_disclosed
          - other
          - unmapped_value
      required:
      - value
      - source_value
    ISO3166_2SubDivisionEnum:
      type: object
      properties:
        source_value:
          type: string
        value:
          type: string
          enum:
          - AD-07
          - AD-02
          - AD-03
          - AD-08
          - AD-04
          - AD-05
          - AD-06
          - AE-AJ
          - AE-AZ
          - AE-FU
          - AE-SH
          - AE-DU
          - AE-RK
          - AE-UQ
          - AF-BDS
          - AF-BDG
          - AF-BGL
          - AF-BAL
          - AF-BAM
          - AF-DAY
          - AF-FRA
          - AF-FYB
          - AF-GHA
          - AF-GHO
          - AF-HEL
          - AF-HER
          - AF-JOW
          - AF-KAB
          - AF-KAN
          - AF-KAP
          - AF-KHO
          - AF-KDZ
          - AF-LAG
          - AF-LOG
          - AF-NAN
          - AF-NIM
          - AF-PIA
          - AF-PAR
          - AF-SAR
          - AF-TAK
          - AF-URU
          - AG-11
          - AG-03
          - AG-04
          - AG-06
          - AG-07
          - AG-08
          - AI-XX-1
          - AL-01
          - AL-09
          - AL-02
          - AL-03
          - AL-04
          - AL-05
          - AL-06
          - AL-07
          - AL-08
          - AL-10
          - AL-11
          - AL-12
          - AM-AG
          - AM-AR
          - AM-AV
          - AM-ER
          - AM-GR
          - AM-KT
          - AM-LO
          - AM-SH
          - AM-SU
          - AM-TV
          - AM-VD
          - AO-BGO
          - AO-BGU
          - AO-BIE
          - AO-CAB
          - AO-CCU
          - AO-CNO
          - AO-CUS
          - AO-CNN
          - AO-HUA
          - AO-HUI
          - AO-LUA
          - AO-LNO
          - AO-LSU
          - AO-MAL
          - AO-MOX
          - AO-NAM
          - AO-UIG
          - AO-ZAI
          - AQ-XX-1
          - AR-B
          - AR-K
          - AR-H
          - AR-U
          - AR-C
          - AR-X
          - AR-W
          - AR-E
          - AR-P
          - AR-Y
          - AR-L
          - AR-F
          - AR-M
          - AR-N
          - AR-Q
          - 

# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stackone/refs/heads/main/openapi/stackone-employees-api-openapi.yml