Harri Franchisee Employee API
The Franchisee Employee API from Harri — 6 operation(s) for franchisee employee.
OpenAPI Specification
openapi: 3.2.0
info:
title: Harri Employee Open Franchisee 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: Franchisee Employee
paths:
/api/v3/franchisees/{franchiseeId}/employees:
get:
tags:
- Franchisee Employee
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
- 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: FranshiseesGetEmployees
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
employees:
type: array
items:
$ref: '#/components/schemas/EmployeesListV2'
pagination:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
total_pages:
type: integer
/api/v3/franchisees/{franchiseeId}/employees/{employeeId}/basic_info:
put:
tags:
- Franchisee Employee
summary: Update employee API
description: Update employee
operationId: FranshiseesUpdateEmployee
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
- 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/franchisees/{franchiseeId}/employees/:
get:
tags:
- Franchisee Employee
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
- 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: FranchiseesListEmployeesV4
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/franchisees/{franchiseeId}/employees/{employeeId}/profile:
get:
tags:
- Franchisee Employee
summary: Get employee profile API
description: Get employee profile.
operationId: FranchiseesGetEmployeeProfileV5
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
- 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/franchisees/{franchiseeId}/employees/{employeeId}:
get:
tags:
- Franchisee Employee
summary: Get employee by id API
description: Get employee by harri employee id.
operationId: FranchiseesGetEmployeeByIdV6
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
- 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/franchisees/{franchiseeId}/employees:
post:
tags:
- Franchisee Employee
summary: Create employee API
description: Create employee API
operationId: FranchiseesCreateEmployeeV7
parameters:
- name: franchiseeId
in: path
required: true
schema:
type: number
requestBody:
description: Employee data
content:
application/json:
schema:
type: object
properties:
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'
title:
type: string
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_amount:
type: number
tronc_rate:
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:
all
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/harri/refs/heads/main/openapi/harri-franchisee-employee-api-openapi.yml