Harri Employee API

openapi: 3.2.0
info:
  title: Harri Open Employee API
  description: 'API for managing and retrieving employee data in the Harri system. - Notice: Harri''s API enforces a rate limit of 400 requests per minute. Once you exceed this limit, an HTTP 403 error is returned with a body that informs you that the limit has been exceeded. Please examine the API returns for this error so your software can respond appropriately. After 4 June, 2026, the rate limiting error will change from 403 to 429.'
  termsOfService: https://harri.com/terms
  version: 1.0.0
servers:
- url: https://gateway.harri.com/open-api-hub
tags:
- name: Employee
paths:
  /api/v3/employees/{employeeId}/basic_info:
    put:
      tags:
      - Employee
      summary: Update employee API
      description: Update employee
      operationId: UpdateEmployee
      parameters:
      - name: employeeId
        in: path
        description: ID of employee to return
        required: true
        schema:
          type: string
      requestBody:
        description: employee
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: employee email
                first_name:
                  type: string
                  description: employee first name
                last_name:
                  type: string
                  description: employee last name
                middle_name:
                  type: string
                  description: employee middle name
                geid:
                  type: string
                birth_date:
                  type: string
                  format: date
                  description: employee birth date
                national_number:
                  type: string
                  description: National number
                phone:
                  type: string
                  format: phone
                  description: employee phone number
                home_phone:
                  type: string
                  format: phone
                  description: home phone number
                gender:
                  type: string
                  enum:
                  - MALE
                  - FEMALE
                  - NO_IDENTIFY
                  description: employee gender
                address:
                  allOf:
                  - $ref: '#/components/schemas/Address'
                  - type: object
                    required:
                    - address_line_1
                    - postal_code
                    - country_code
                vsl:
                  type: string
                  enum:
                  - IN
                  - OUT
                title:
                  type: string
        required: true
      responses:
        '200':
          description: successful operation
      security:
      - oAuth2ClientCredentials:
        - ''
  /api/v4/employees/:
    get:
      tags:
      - Employee
      parameters:
      - name: status
        in: query
        description: to get terminated or active employee, default active
        schema:
          type: string
          enum:
          - ACTIVE
          - TERMINATED
      - name: limit
        in: query
        description: specify the number of rows to return
        schema:
          type: integer
          minimum: 1
      - name: page
        in: query
        description: specify the number of rows to skip
        schema:
          type: integer
          minimum: 0
      - name: location_id
        in: query
        description: specify the location id to filter
        schema:
          type: string
      - name: is_primary
        in: query
        description: retrieve primary employees of the provided location_id
        schema:
          type: boolean
      - name: loa_status
        in: query
        required: false
        description: 'Filters employees by active LOA (Leave of Absence) status. When provided, only employees currently marked as ''ON_LEAVE'' within the retrieved page will be returned.

          '
        schema:
          type: string
          enum:
          - ON_LEAVE
          example: ON_LEAVE
      - name: payroll_id
        in: query
        description: filter employees by payroll_id
        schema:
          type: string
      - name: geid
        in: query
        description: filter employees by geid (external middleware id)
        schema:
          type: string
      summary: Get employees API
      description: Get employees.
      operationId: ListEmployeesV4
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  employees:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmployeesListV3'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
  /api/v5/employees/{employeeId}/profile:
    get:
      tags:
      - Employee
      summary: Get employee profile API
      description: Get employee profile.
      operationId: GetEmployeeProfileV5
      parameters:
      - name: employeeId
        in: path
        description: ID of employee to return
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeProfileV2'
        '400':
          description: Invalid ID supplied
        '404':
          description: employee not found
          content: {}
      security:
      - oAuth2ClientCredentials:
        - ''
  /api/v6/employees/{employeeId}:
    get:
      tags:
      - Employee
      summary: Get employee by id API
      description: Get employee by harri employee id.
      operationId: GetEmployeeByIdV6
      parameters:
      - name: employeeId
        in: path
        description: ID of employee to return
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeAggregatedInfoV6'
        '400':
          description: Invalid ID supplied
        '404':
          description: employee not found
          content: {}
      security:
      - oAuth2ClientCredentials:
        - ''
  /api/v7/employees:
    post:
      tags:
      - Employee
      summary: Create employee API
      description: Create employee API
      operationId: CreateEmployeeV7
      requestBody:
        description: Employee data
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                id:
                  type: string
                  description: A unique ID supplied by customers or third parties. If not provided, Harri will generate one. This is supported only if external mapping is enabled for the client.
                email:
                  type: string
                  format: email
                  description: If phone number is not provided, employee email must be provided.
                first_name:
                  type: string
                  description: employee first name
                last_name:
                  type: string
                  description: employee last name
                middle_name:
                  type: string
                  description: employee middle name
                known_as:
                  type: string
                birth_date:
                  type: string
                  format: date
                  description: employee birth date
                national_number:
                  type: string
                  description: national_number max length is 12 cahrechters
                phone:
                  type: string
                  format: phone
                  description: If email is not provided, employee phone number must be provided.
                home_phone:
                  type: string
                  format: phone
                  description: home phone number
                gender:
                  type: string
                  enum:
                  - MALE
                  - FEMALE
                  - NO_IDENTIFY
                  description: employee gender
                geid:
                  type: string
                address:
                  allOf:
                  - $ref: '#/components/schemas/Address'
                  - type: object
                    properties:
                      county:
                        type: string
                    required:
                    - account_number
                    - postal_code
                    - country_code
                hire_date:
                  type: string
                  format: date
                  description: employee hire date
                bank_account:
                  type: object
                  properties:
                    routing_number:
                      type: string
                    account_number:
                      type: string
                    registration_number:
                      type: string
                    account_type:
                      type: string
                      enum:
                      - SAVINGS
                      - CHECKING
                    bank_name:
                      type: string
                    account_name:
                      type: string
                    sort_code:
                      type: string
                    bank_branch:
                      type: string
                  required:
                  - account_number
                job_titles:
                  type: array
                  items:
                    type: object
                    properties:
                      job_title_id:
                        type: number
                      level:
                        type: number
                    required:
                    - job_title_id
                    - level
                payroll_id:
                  type: string
                  minLength: 1
                vsl:
                  type: string
                  enum:
                  - IN
                  - OUT
                location_id:
                  type: string
                pay_type:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - SALARIED
                      - HOURLY
                      - WEIGHTED_SHIFT
                    cross_location_mode:
                      type:
                      - string
                      - 'null'
                      enum:
                      - FIXED
                      - FLEXIBLE
                      description: Required when the pay type is set to HOURLY.
                  required:
                  - type
                max_weekly_hours:
                  type: object
                  properties:
                    working_patterns:
                      type: array
                      items:
                        type: object
                        properties:
                          days_count:
                            type:
                            - integer
                            - 'null'
                          total_hours:
                            type: number
                          order:
                            type: integer
                          working_pattern_days:
                            type: array
                            items:
                              type: object
                              properties:
                                day:
                                  type: string
                                  enum:
                                  - MON
                                  - TUE
                                  - WED
                                  - THU
                                  - FRI
                                  - SAT
                                  - SUN
                                hours_count:
                                  type:
                                  - number
                                  - 'null'
                tronc_point:
                  type: object
                  properties:
                    value:
                      type: number
                  required:
                  - value
                tronc_amount:
                  type: object
                  properties:
                    value:
                      type: number
                  required:
                  - value
                position:
                  type: object
                  properties:
                    code:
                      type: string
                    tipped_statuses:
                      type: object
                      properties:
                        is_tipped:
                          type: boolean
                    hourly_rate:
                      type: object
                      properties:
                        value:
                          type: number
                        tronc_point:
                          type: number
                        tronc_rate:
                          type: number
                        tronc_amount:
                          type: number
                      required:
                      - value
                    cost_centers:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: number
                          value:
                            type: object
                            properties:
                              id:
                                type: number
                            required:
                            - id
                        required:
                        - id
                  required:
                  - code
              required:
              - first_name
              - last_name
              - hire_date
              - location_id
              - pay_type
              - position
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedEmployeeV7'
      security:
      - oAuth2ClientCredentials:
        - ''
components:
  schemas:
    EmployeeCustomFieldsCityWithholdingDetails:
      type: object
      description: Section 6 - City Withholding Details - CITY_WITHHOLDING_DETAILS
      properties:
        city_additional_withholding_amount:
          type: number
          format: double
          description: Decimal, 2 decimal places
        city_exempt_status:
          type: string
        city_marital_status:
          type: string
        city_number_of_exceptions:
          type: integer
    HourlyRate:
      type: object
      properties:
        id:
          type: number
        value:
          type: number
        start_date:
          type: string
          format: date
        tronc_point:
          type: number
        tronc_amount:
          type: number
        tronc_rate:
          type: number
    TroncPoint:
      type: object
      properties:
        id:
          type: number
        value:
          type: number
        start_date:
          type: string
          format: date
    Address:
      type: object
      properties:
        country_code:
          type: string
          example: US
        state_code:
          type: string
          example: NY
        city:
          type: string
        address_line_1:
          type: string
        address_line_2:
          type: string
        postal_code:
          type: string
    EmployeeProfileV2:
      allOf:
      - $ref: '#/components/schemas/EmployeeBasicInfo'
      - type: object
        properties:
          financial_unit_location_id:
            type: integer
          loa_status:
            type:
            - string
            - 'null'
          title:
            type:
            - string
            - 'null'
          status:
            type: string
            enum:
            - ACTIVE
            - TERMINATED
          address:
            $ref: '#/components/schemas/Address'
          employer:
            type: object
            properties:
              id:
                type:
                - number
                - 'null'
              email:
                type: string
                format: email
                description: employer email
              first_name:
                type: string
                description: employer first name
              last_name:
                type: string
                description: employer last name
          employment_period:
            $ref: '#/components/schemas/EmploymentPeriod'
          job_titles:
            type: array
            items:
              $ref: '#/components/schemas/EmployeeJobTitle'
          vsl:
            type: string
            enum:
            - IN
            - OUT
          locations:
            type: array
            items:
              type: object
              allOf:
              - $ref: '#/components/schemas/Location'
              - type: object
                properties:
                  is_primary:
                    type: boolean
                  is_active:
                    type: boolean
                  location_periods:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocationPeriod'
                  payroll_id:
                    type: string
                  pos_id:
                    type: string
          positions:
            type: array
            items:
              allOf:
              - $ref: '#/components/schemas/EmployeePosition'
              - type: object
                properties:
                  hourly_rates:
                    type: array
                    items:
                      $ref: '#/components/schemas/HourlyRate'
                  tipped_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/TippedStatus'
          pay_types:
            type: array
            items:
              $ref: '#/components/schemas/PayType'
          tronc_points:
            type: array
            items:
              $ref: '#/components/schemas/TroncPoint'
          tronc_amounts:
            type: array
            items:
              $ref: '#/components/schemas/TroncAmount'
          max_weekly_hours:
            type: array
            items:
              $ref: '#/components/schemas/MaxWeeklyHoursV2'
    MaxWeeklyHoursV4:
      type: object
      description: 'Max Weekly Hours entry (v4+ shape) exposing a list of `working_patterns` and the derived `average_weekly_hours`.

        '
      properties:
        id:
          type: number
        start_date:
          type: string
          format: date
        average_weekly_hours:
          type: number
        working_patterns:
          type: array
          items:
            $ref: '#/components/schemas/WorkingPatternV4'
    EmployeeCustomFieldsEqualOpportunityInformation:
      type: object
      description: Section 8 - Equal Opportunity Information - EQUAL_OPPORTUNITY_INFORMATION
      properties:
        caring_responsibilities:
          type: string
        disability_status:
          type: string
        ethnicity:
          type: string
        flexible_working_arrangements:
          type: string
        gender_identity:
          type: string
        other_ethnicity:
          type: string
        other_flexible_working_arrangements:
          type: string
        other_gender_identity:
          type: string
        other_religious_belief:
          type: string
        other_sexual_orientation:
          type: string
        religious_belief:
          type: string
        sexual_orientation:
          type: string
        specific_ethnicity:
          type: string
        type_of_caring_responsibilities:
          type: string
    Location:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        country_code:
          type: string
        state_code:
          type: string
        city:
          type: string
    CreatedEmployeeV7:
      allOf:
      - $ref: '#/components/schemas/EmployeeBasicInfo'
      - type: object
        properties:
          user_id:
            type:
            - number
            - 'null'
          title:
            type:
            - string
            - 'null'
          gender:
            type: string
            enum:
            - MALE
            - FEMALE
            - NO_IDENTIFY
            description: employee gender
          national_number:
            type: string
            description: National number
          financial_unit_location_id:
            type: integer
          status:
            type: string
            enum:
            - ACTIVE
            - TERMINATED
          address:
            $ref: '#/components/schemas/Address'
          employer:
            type: object
            properties:
              email:
                type: string
                format: email
                description: employer email
              first_name:
                type: string
                description: employer first name
              last_name:
                type: string
                description: employer last name
          employment_period:
            $ref: '#/components/schemas/EmploymentPeriod'
          job_titles:
            type: array
            items:
              $ref: '#/components/schemas/EmployeeJobTitle'
          vsl:
            type: string
            enum:
            - IN
            - OUT
          locations:
            type: array
            items:
              type: object
              allOf:
              - $ref: '#/components/schemas/Location'
              - type: object
                properties:
                  is_primary:
                    type: boolean
                  is_active:
                    type: boolean
                  payroll_id:
                    type: string
                  pos_id:
                    type: string
                  location_periods:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocationPeriod'
          positions:
            type: array
            items:
              allOf:
              - $ref: '#/components/schemas/Position'
              - type: object
                properties:
                  id:
                    type: number
                  location_id:
                    type: integer
                  is_primary:
                    type: boolean
                  hourly_rates:
                    type: array
                    items:
                      $ref: '#/components/schemas/HourlyRate'
                  tipped_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/TippedStatus'
                  cost_centers:
                    type: array
                    items:
                      $ref: '#/components/schemas/CostCenter'
          pay_types:
            type: array
            items:
              $ref: '#/components/schemas/PayType'
          annual_rates:
            type: array
            items:
              $ref: '#/components/schemas/AnnualRate'
          tronc_points:
            type: array
            items:
              $ref: '#/components/schemas/TroncPoint'
          tronc_amounts:
            type: array
            items:
              $ref: '#/components/schemas/TroncAmount'
          max_weekly_hours:
            type: array
            items:
              $ref: '#/components/schemas/MaxWeeklyHoursV2'
          bank_account:
            type: object
            properties:
              id:
                type: number
              bank_branch:
                type:
                - string
                - 'null'
              bic:
                type:
                - string
                - 'null'
              iban:
                type:
                - string
                - 'null'
              routing_number:
                type: string
              account_number:
                type: string
              registration_number:
                type: string
              account_type:
                type: string
                enum:
                - SAVINGS
                - CHECKING
              bank_name:
                type: string
              account_name:
                type: string
              sort_code:
                type: string
            required:
            - account_number
    MaxWeeklyHoursV2:
      type: object
      properties:
        id:
          type: number
        start_date:
          type: string
          format: date
        average_weekly_hours:
          type: number
        working_patterns:
          type: array
          items:
            $ref: '#/components/schemas/WorkingPatternV2'
    Position:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        category:
          type: object
          properties:
            id:
              type: number
            code:
              type: string
            name:
              type: string
    EmployeePosition:
      allOf:
      - $ref: '#/components/schemas/Position'
      - type: object
        properties:
          id:
            type: number
          location_id:
            type: integer
          is_primary:
            type: boolean
            description: Indicates whether this position is the primary role for a user. This value is determined based on the existence of a PRIMARY_POSITION service.
          cost_centers:
            type: array
            items:
              $ref: '#/components/schemas/CostCenter'
    TippedStatus:
      type: object
      properties:
        id:
          type: number
        is_tipped:
          type: boolean
        start_date:
          type: string
          format: date
    EmploymentPeriod:
      type: object
      properties:
        id:
          type: number
        hire_date:
          type: string
          format: date
          description: employee hire date
        leave_date:
          type:
          - string
          - 'null'
          format: date
          description: employee leave date
        termination_reason:
          type:
          - object
          - 'null'
          properties:
            code:
              type: string
            name:
              type: string
    EmployeeJobTitle:
      type: object
      allOf:
      - $ref: '#/components/schemas/JobTitle'
      - type: object
        properties:
          level:
            type: string
            description: number with quotations like "5"
    EmployeeCustomFieldsPersonalInfoAdditionalInfo:
      type: object
      description: Section 1 - Additional Information - PERSONAL_INFO_ADDITIONAL_INFO
      properties:
        certificate_of_sponsorship_number:
          type: string
        dbs_cert_number:
          type: string
        dbs_expiry_date:
          type: string
        dbs_issue_date:
          type: string
        disabled_veteran:
          type: string
        ethnicity_2:
          type: string
        first_language:
          type: string
        marital_status:
          type: string
        military_veteran_status:
          type: string
        nationality:
          type: string
        national_origin:
          type: string
        nmc_date_checked:
          type: string
        nmc_expiry_date:
          type: string
        nmc_pin_number:
          type: string
        passport_expiry_date:
          type: string
        passport_number:
          type: string
        person_marital_status:
          type: string
        pronoun:
          type: string
        student_permit_exp_date:
          type: string
        student_status:
          type: string
        veteran_type:
          type: string
    AnnualRate:
      type: object
      properties:
        id:
          type: number
        value:
          type: number
        start_date:
          type: string
          format: date
    EmployeeAggregatedInfoV6:
      allOf:
      - $ref: '#/components/schemas/EmployeeBasicInfo'
      - type: object
        additionalProperties: true
        description: Additional dynamic custom fields (e.g., `personal_info_additional_info`) may appear at the top level — they are flattened from the underlying `custom_fields` map during serialization.
        properties:
          title:
            type:
            - string
            - 'null'
          gender:
            type: string
            enum:
            - MALE
            - FEMALE
            - NO_IDENTIFY
            description: employee gender
          national_number:
            type: string
            description: National number
          financial_unit_location_id:
            type: integer
          status:
            type: string
            enum:
            - ACTIVE
            - TERMINATED
          address:
            $ref: '#/components/schemas/Address'
          employer:
            type: object
            properties:
              id:
                type:
                - number
                - 'null'
              email:
                type: string
                format: email
                description: employer email
              first_name:
                type: string
                description: employer first name
              last_name:
                type: string
                description: employer last name
          employment_period:
            $ref: '#/components/schemas/EmploymentPeriod'
          job_titles:
            type: array
            items:
              $ref: '#/components/schemas/EmployeeJobTitle'
          vsl:
            type: string
            enum:
            - IN
            - OUT
          locations:
            type: array
            items:
              type: object
              allOf:
              - $ref: '#/components/schemas/Location'
              - type: object
                properties:
                  is_primary:
                    type: boolean
                  is_active:
                    type: boolean
                  location_periods:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocationPeriod'
                  payroll_id:
                    type: string
                  pos_id:
                    type: string
          positions:
            type: array
            items:
              allOf:
              - $ref: '#/components/schemas/EmployeePosition'
              - type: object
                properties:
                  hourly_rates:
                    type: array
                    items:
                      $ref: '#/components/schemas/HourlyRate'
                  tipped_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/TippedStatus'
          pay_types:
            type: array
            items:
              $ref: '#/components/schemas/PayType'
          annual_rates:
            type: array
            items:
              $ref: '#/components/schemas/AnnualRate'
          tronc_points:
            type: array
            items:
              $ref: '#/components/schemas/TroncPoint'
          tronc_amounts:
            type: array
            items:
              $ref: '#/components/schemas/TroncAmount'
          max_w

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