Product Events

Events that occur in the Freshteam product, such as saving employee information, updating employee information, or moving a candidate’s information to the New Hire Queue after a hiring confirmation, are termed as product events. You can enable product events to trigger apps. To do this, configure event listeners in the server.js file. When a product event occurs, the corresponding event listener invokes a callback method. The app logic in the callback method runs with the help of the event-specific payload passed to the callback method.

Configure Events

To register a product event and the corresponding callback:

  1. From your app’s root directory, navigate to the manifest.json file.
  2. Include the events attribute, specifying the product event and the corresponding callback methods as follows:
    Copied Copy
    1
    2
    3
    4
    5
    "events": { "<eventName>": { "handler": "<eventCallbackMethod>" } }

    Note: Include only one callback method for an event. Multiple events can access the same callback method.

  3. Navigate to the server.js file.
  4. In the exports block, enter the callback function definition as follows:
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    exports = { // args is a JSON block containing the payload information // args["iparam"] will contain the installation parameter values //eventCallbackMethod is the call-back function name specified in manifest.json eventCallbackMethod: function(args) { console.log("Logging arguments from the event: " + JSON.stringify(payload)); }};

Payload Attributes

When a product event occurs, an event-specific payload is passed to the callback method.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ "account_id" : "value", "domain" : "value", "event" : "value", "region" : "value", "timestamp" : "value", "data" : { //Contains the list of objects related to the event. }, "iparams" : { "Param1" : "value", "Param2" : "value" } }
EXPAND ↓

The payload is a JSON object with the following attributes.

Attribute Type Description
account_id string Identifier of the Freshteam account, auto-generated when the account is configured for an organization.
domain string Domain name for the Freshteam account. For example, acn.freshteam.com.
event string Identifier of the product event.
region string Region where the Freshteam account is deployed.
Possible values: US, EU, EUC, AUS, and IND.
timestamp number Timestamp of when the product event occurs, specified in the epoch format.
iparams object Installation parameters specified as a JSON object of <parameter name>: <parameter value> pairs.
data object Event-specific Freshteam data, specified as a JSON object of key:value pairs.
onEmployeeCreate

When an employee record is created in the Freshteam system, the onEmployeeCreate event is triggered.

Register the onEmployeeCreate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onEmployeeCreate": { "handler": "onEmployeeCreateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onEmployeeCreateCallback: function(payload) { console.log("Arguments from the onEmployeeCreate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
{ "timestamp": 1496400354326, "account_id": "15", "domain": "acn.freshteam.com", "event": "onEmployeeCreate", "region": "US", "data": { "employee": { "id": 17, "created_at": "2020-04-02 07:25:52 UTC", "updated_at": "2020-04-02 07:25:55 UTC", "deleted": false, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_job_category": null, "eeo_company_code": null, "hire_reason": null, "id_card_details": null, "workstation_number": null, "secondary_business_email": null, "work_numbers": [], "nick_name": null, "date_of_birth": null, "marital_status": null, "gender": null, "blood_group": null, "emergency_contacts": [], "social_profiles": [], "address": { "street": "", "state": "", "city": "" }, "phone_numbers": [], "communication_address": { "same_as_residential": false, "communication_street": "", "communication_state": "", "communication_city": "" }, "secondary_last_name": null, "hereditary_last_name": null, "legal_name": null, "previous_name": null, "previous_name_change_date": null, "place_of_birth": null, "im_address": null, "country_of_birth": null, "flsa_required": false, "user_title_id": null, "user_suffix_name_id": null, "user_honorary_suffix_id": null, "user_professional_suffix_id": null, "user_academic_suffix_id": null, "citizenship_status_id": null, "designation": "Regional Manager", "joining_date": null, "internship_end_date": null, "probation_start_date": null, "probation_end_date": null, "job_code": null, "job_exempt": null, "scheduled_weekly_hours": null, "work_hours": null, "start_time": null, "end_time": null, "branch_id": 1, "team_id": 1, "business_unit_id": null, "sub_department_id": null, "department_id": 3, "reporting_to_id": null, "hr_incharge_id": null, "level_id": 6, "shift_id": null, "user_function_id": null, "cost_center_id": null, "employment_end_date": null, "retirement_eligibility_date": null, "expected_retirement_date": null, "actual_retirement_date": null, "termination_date": null, "termination_reason": null, "notice_period": null, "notice_start_date": null, "notice_end_date": null, "retirement_status_id": null, "termination_category_id": null, "custom_fields": { "fwef_cf_str01": "custom_text", "uiouoi_cf_str03": { "id": 0, "value": null }, "tryt_cf_str02": null }, "rehire_eligibility": null, "rehire_status": null, "previous_joining_date": null, "previous_exit_date": null, "original_hire_date": null, "avatar_url": null, "first_name": "Alayna", "middle_name": null, "last_name": "Marvin", "employee_id": null, "status": "active", "official_email": "alayna@freshteam.com", "personal_email": "alayna_personal@freshteam.com", "confirmed": false, "account_admin": false, "language": "en", "time_zone": "US/Pacific", "employee_type": "full_time" }, "associations": { "branch": { "id": 1, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Default - Head office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": true, "date_format": "MonthFirst" }, "team": { "id": 1, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Business" }, "department": { "id": 3, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Administration" }, "level": { "id": 6, "created_at": "2020-03-23 08:38:43 UTC", "updated_at": "2020-03-23 08:38:43 UTC", "deleted": false, "name": "IC6" }, "roles": [ { "id": 8, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "name": "Employee", "description": "Can view limited set of information of other Employees, request timeoff, view company job postings, and refer a candidate to the Organization.", "default": true } ], "dependents": [], "reportees": [], "incharge_users": [], "prev_employments": [], "qualifications": [], "bank_accounts": [], "compensation_details": [], "bonuses": [], "stocks": [], "awards": [], "certificates": [], "honors": [], "licenses": [], "background_verification_details": [], "visas": [], "government_documents": [], "additional_teams": [], "additional_managers": [], "additional_hr_managers": [], "languages": [] }, "actor": { "id": 13, "name": "Sean Dr. Greenfelder", "email": "651497celestina@example.com" } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
employee employee object Employee information that is saved when a new employee’s record is created in the Freshteam system. The record creation triggers the onEmployeeCreate event.
associations associations object All associated objects of the employee object, that specify additional information pertaining to the employee. This includes information such as the branch, team, and department to which the employee belongs, role of the employee, employee’s dependent information, compensation details, and so on.
actor actor object Information pertaining to the user who created the employee record.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user; a concatenation of employee.first_name employee.middle_name employee.last_name.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.

Attributes of the employee object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the employee object, auto-generated when the employee record is created.
created_at string Timestamp of when the employee record is created, specified in the UTC format.
updated_at string Timestamp of when the employee information is last updated, specified in the UTC format. For onEmployeeCreate, this value is the same as the created_at value.
deleted boolean Specifies whether an employee record is deleted from the Freshteam system.
For onEmployeeCreate and onEmployeeUpdate triggered by record updation, this value is false.
For onEmployeeUpdate triggered by record deletion, this value is true.
first_name string Business name of the employee.
middle_name string Middle name of the employee.
last_name string Last name of the employee.
official_email string Official email address of the employee.
employee_id string Employee ID provided by the organization that uses Freshteam.
status string Employment status of an employee.
Possible values:
  • active: Current employee, records are active and saved.
  • inactive: Employee is in a long leave of absence, records are archived.
eeo_vetran string Type of vetran recruited based on the Equal Employment Opportunity (EEO) policy of an organization that enables employing veterans from armed forces.
Possible values:
  • Protected vetran: Employee has served in active duty in the armed forces.
  • Unprotected vetran: Employee has not served in active duty but was involved in a campaign.
  • I don’t wish to answer
eeo_ethinicity string Ethnicity of the employee who is recruited based on the EEO policy of the organization.
Possible values:
  • American Indian or Alaska Native (Not Hispanic or Latino)
  • Asian or Indian Subcontinent (Not Hispanic or Latino)
  • Black or African American (Not Hispanic or Latino)
  • Hispanic or Latino
  • Native Hawaiian or Other Pacific Islander (Not Hispanic or Latino)
  • Two or More Races (Not Hispanic or Latino)
  • White (Not Hispanic or Latino)
  • I don’t wish to answer
eeo_disabled string Specifies whether the employee is recruited based on the EEO policy of the organization that enables employing people with disabilities.
Possible values: Yes, No, I don’t wish to answer
eeo_job_category string EEO job class under which the employee is recruited.
Possible values:
  • Executive/Senior Level Managers
  • First/Mid Level Managers
  • Professionals
  • Technicians
  • Sales Workers
  • Administrative/Support Workers
  • Craft Workers
  • Operatives
  • Laborers and Helpers
  • Service Workers
eeo_company_code string EEO company code that the EEO commission assigns to an organization.
hire_reason string Reason the interview panel provides for hiring the employee.
id_card_details string Number or code associated with the ID card provided to the employee.
work_numbers array of work number objects Official phone numbers of the employee, specified as an array of work number objects.
Attributes of the work number object:
name (string): Type of phone number. Possible values: Work, Office Ext., Mobile, Others
number (string): Official contact number of the employee.
workstation_number string Work desk number of the employee.
secondary_business_email string Alternate work contact information for the employee.
nick_name string Alternate display name for the employee, in the Freshteam system.
date_of_birth string Birth date of the employee.
marital_status string Marital status of the employee.
Possible values: single, married
gender string Gender of the employee.
Possible values: male, female
blood_group string Blood group of the employee.
Possible values: A−, B−, O−, B+, O+, A+, A1+, A1B-, AB+, AB-, A1B+, A2+, A2B-, A2B+, A1-
emergency_contacts array of emergency contact objects Details of the people to be contacted if there is an emergency situation, specified as an array of emergency contact objects.
Attributes of the emergency contact object:
name (string)
relationship (string): Possible values: Parent, Father, Mother, Spouse, Husband, Wife, Child, Son, Daughter, Sibling, Brother, Sister
contant_number (string)
address (string)
social_profiles array of objects List of all social platforms in which the employee is available, specified as a social_profile array of objects.
Attributes of the array object:
name (string): Name of the social medium.
url (string): Link to the employee's social medium handle.
address address object Residential address of the employee.
Attributes of the address object:
street (string)
state (string)
city (string)
country_code (string)
zip_code (string)
communication_address communication address object Address to which all official communication is sent.
Attributes of the communication address object:
communication_street (string)
communication_city (string)
communication_state (string)
communication_country_code (string)
communication_zip_code (string)
same_as_residential (boolean): The attribute is part of the employee object only if the attribute value is false.
designation string Job title of the employee.
phone_numbers array of phone number objects Contact numbers of the employee, specified as an array of phone number objects.
Attributes of the phone number object::
name (string): Type of phone number. Possible values: Home, Main, Mobile, Others
number (string): Personal contact number of the employee.
secondary_last_name string Second surname of the employee, if the employee has a composite surname.
hereditary_last_name string Family name part of the employee’s surname, if the employee has a composite surname.
legal_name string Registered name of the employee.
previous_name string Previous name of the employee, if the employee has changed the official name.
previous_name_change_date string Date from when the employee’s new name is official, as per the legal records.
place_of_birth string City where the employee was born.
im_address string Official instant messenger address of the employee.
country_of_birth string Country where the employee was born.
flsa_required boolean Specifies whether the employee requires legal protection under the Fair Labour Standards Act (FLSA).
Possible values: true, false
job_code string Job code of the employee, as specified in FLSA.
job_exempt boolean Specifies whether the job for which the employee is recruited is exempted from protection offered by FLSA.
Possible values: Exempted, Not exempted
user_title_id integer Identifier of the title associated with the employee.
When an organization configures the list of possible titles in the Freshteam system, an id is auto-generated for each title. For example, if the organization configures Mr. and Ms. as the possible titles, the corresponding auto-generated ids can be 12 and 13. When an employee record is created, if Mr. is chosen as the Title of the employee, user_title_id is 12.
user_suffix_name_id integer Identifier of the name suffix associated with the employee.
When an organization configures the list of possible name suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures Jr. and Sr. as the possible suffixes, the corresponding auto-generated ids can be 14 and 15. When an employee record is created, if Jr. is chosen as the Suffix Name of the employee, user_suffix_name_id is 14.
user_honorary_suffix_id integer Identifier of the honorary title bestowed to the employee.
When an organization configures the list of possible honorary titles in the Freshteam system, an id is auto-generated for each title. For example, if the organization configures OBE and MBE as the possible honours, the corresponding auto-generated ids can be 16 and 17. When an employee record is created, if OBE is chosen as the Honorary Title of the employee, user_honorary_suffix_id is 16.
user_professional_suffix_id integer Identifier of the professional suffix associated with the employee.
When an organization configures the list of possible professional suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures CFA and CPA as the possible suffixes, the corresponding auto-generated ids can be 18 and 19. When an employee record is created, if CPA is chosen as the Professional Suffix of the employee, user_professional_suffix_id is 18.
user_academic_suffix_id integer Identifier of the academic qualification, which can be specified as a suffix, associated with the employee.
When an organization configures the list of possible academic suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures M.S and Ph.D as the possible suffixes, the corresponding auto-generated ids can be 20 and 21. When an employee record is created, if M.S is chosen as the Academic Suffix of the employee, user_academic_suffix_id is 20.
citizenship_status_id integer Identifier of the employee’s citizenship status.
When an organization configures the list of possible citizenship statuses in the Freshteam system, an id is auto-generated for each status. For example, if the organization configures Naturalised and By Birth as the possible statuses, the corresponding auto-generated ids can be 22 and 23. When an employee record is created, if Naturalised is chosen as the Citizenship Status of the employee, citizenship_status_id is 22.
joining_date string Date when the employee joins the organization, specified in the YYYY-MM-DD format.
internship_end_date string Date when the employee’s internship ends. This value is null for employees who are not interns.
probation_start_date string Date when the employee’s probation period starts, specified in the YYYY-MM-DD format.
probation_end_date string Date when the employee’s probation period ends, specified in the YYYY-MM-DD format.
scheduled_weekly_hours integer Number of hours scheduled for the employee’s job position. If weekly hours are scheduled for a position, all work beyond the scheduled hours is considered for over-time.
work_hours integer Number of hours the employee is expected to work.
start_time string In a day, the typical work starting time of the employee, set by the organization.
end_time string In a day, the typical work ending time of the employee, set by the organization.
branch_id string Identifier of the branch to which the employee belongs. This is the branch.id value that is auto-generated when the branch’s information is configured in Freshteam.
team_id string Identifier of the primary work group to which the employee belongs. This is the team.id value that is auto-generated when the team’s information is configured in Freshteam.
business_unit_id string Identifier of the business function to which the employee belongs.
When a business unit is configured in Freshteam, a business unit object is created and an id is auto-generated. business_unit_id is this id value. The name attribute of the object identifies the business units. For example, DevOps.
department_id string Identifier of the department (job role) to which the employee belongs. This is the department.id value that is auto-generated when the department’s information is configured in Freshteam.
sub_department_id string Identifier of the subcategory of the job role to which the employee belongs. When a sub-department is configured in Freshteam, a sub-department object is created and an id is auto-generated. sub_department_id is this id value. The name attribute of the object identifies the sub-department.
reporting_to_id string Identifier of the person assigned as the reporting manager of the employee. This is the employee.id value that is auto-generated when the reporting manager’s employee record is stored in Freshteam.
hr_incharge_id string Identifier of the person assigned as the HR incharge of the employee. This is the employee.id value that is auto-generated when the HR incharge’s employee record is stored in Freshteam.
level_id string Identifier of the job band to which the employee belongs. This is the level.id value that is auto-generated when the job band is configured in Freshteam.
shift_id string Identifier of the shift to which the employee belongs.
When a shift is configured in Freshteam, a shift object is created and an id is auto-generated. shift_id is this id value. The name attribute of the object identifies the shift. For example, Day shift, EMEA shift, and so on.
user_function_id string Identifier of the specific function the employee performs as part of a team.
When a user function is configured in Freshteam, a user function object is created and an id is auto-generated. user_function_id is this id value. The name attribute of the object identifies the user function. For example, GTM, design, and so on.
cost_center_id string Identifier of the cost group to which the employee belongs.
Employees are grouped into departments, teams, business units, sub-departments, and cost centers. All organization expenditure specific to the employee is borne by the cost center to which the employee belongs. When a cost centre is configured in Freshteam, a cost centre object is created and an id is auto-generated. cost_center_id is this id value.
employment_end_date string Date by when the employee’s offer of employment ceases, specified in the YYYY-MM-DD format. If a notice period is set for an organization, this value is auto-populated based on the notice period.
retirement_eligibility_date string Date after which the employee is eligible to opt for retirement, specified in the YYYY-MM-DD format.
expected_retirement_date string Date by when the employee is expected to retire, specified in the YYYY-MM-DD format.
actual_retirement_date string Actual date when the employee retires, specified in the YYYY-MM-DD format. For onEmployeeCreate, this value is null.
termination_date string Date when the employee leaves the organization, specified in the YYYY-MM-DD format. For onEmployeeCreate, this value is null.
termination_reason string Reason stating why the employee leaves the organization, specified by the person who updates the employee record. For onEmployeeCreate, this value is null.
termination_category_id integer Identifier of the termination category under which the employee ceases to work for the organization.
When a termination category is configured in Freshteam, a termination category object is created and an id is auto-generated. termination_category_id is this id value. The value attribute of the object identifies the category. For example, Resignation, End of Contract, Involuntary, and so on.
notice_period string Duration the employee has to serve as notice period.
notice_start_date string Starting date of the notice period, updated after the employee’s termination is approved. For onEmployeeCreate, this value is null.
notice_end_date string Ending date of the notice period, updated after the employee’s termination is approved. For onEmployeeCreate, this value is null.
retirement_status_id integer Identifier of the retirement status associated with the employee.
When a retirement status is configured in Freshteam, a field option object is created and an id is auto-generated. retirement_status_id is this id value. The value attribute of the object identifies the status. For example, Retired, Voluntary retirement process, and so on.
rehire_eligibility boolean Specifies whether the employee, whose services have ended, is eligible to be hired in the future. For onEmployeeCreate, this value is null.
rehire_status boolean Specifies whether the employee is a rehire in the organization.
previous_joining_date string Date when the employee started services, in the employee’s previous stint with the organization, specified in the YYYY-MM-DD format.
previous_exit_date string Date when the employee’s offer of employment ceased, in the employee’s previous stint with the organization, specified in the YYYY-MM-DD format.
original_hire_date string Date when the employee’s hiring is finalized and offer of employment rolled out, specified in the YYYY-MM-DD format.
custom_fields object The organization that uses Freshteam can configure custom fields to obtain additional employee information. The custom_fields attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.
avatar_url string Location of the image file that is used to populate the avatar of the employee, in the employee’s personal information page.
personal_email string Personal email address of the employee.
employee_type string Employment terms that apply to the employee. For example, Full Time, Part Time, Contract, Internship, Temporary, Seasonal, Volunteer, and so on.
confirmed boolean Specifies whether an employee has activated the Freshteam log in, by verification through the activation mail sent to the employee’s email. For onEmployeeCreate, this value is null.
account_admin boolean Specifies whether the role associated with the employee is Account Admin. Possible values: true, false
language string Primary language of the branch to which the employee is associated.
time_zone string Time-zone applicable to the branch to which the employee is associated.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
branch branch object Details of the branch to which the employee belongs.
team team object Details of the primary employee group (team) to which the employee belongs.
department department object Details of the department to which the employee belongs.
level level object Details of the job band to which the employee belongs.
roles array of role objects All roles associated with the employee, specified as an array of role objects.
An employee’s access to different entities in the Freshteam system is based on the roles associated with the employee. Role permissions define the access privileges an employee is entitled to. Each role comes with a predefined set of privileges. For more information on roles, see Understanding user roles in Freshteam.
dependents array of dependent objects All details of an employee’s dependents, specified as an array of dependent objects.
reportees array of employee model objects Details of all reportees (employees whose employee.reporting_to_id is the employee.id value of the employee whose record creation triggered onEmployeeCreate), specified as an array of employee model objects.
incharge_users array of employee model objects Details of the HR incharge and reporting manager of the employee, specified as an array of employee model objects.
prev_employments array of previous employment objects All details of the employee’s previous employment positions, specified as an array of previous employment objects.
qualifications array of qualification objects All details of the employee’s education, specified as an array of qualification objects.
bank_accounts array of bank account objects All details of the employee’s bank accounts, specified as an array of bank account objects.
compensation_details array of compensation detail objects All details of the employee’s compensation, specified as an array of compensation detail objects.
bonuses array of bonus objects All details of the employee’s various bonuses, specified as an array of bonus objects.
stocks array of stock objects All details of the employee’s stock grant options, specified as an array of stock objects.
awards array of award objects All awards associated with the employee, specified as an array of award objects.
certificates array of certificate objects All certificates awarded to the employee, specified as an array of certificate objects.
honors array of honor objects All honorary titles associated with the employee, specified as an array of honor objects.
licenses array of license objects Information from all license documents, specified as an array of license objects.
background_verification_details array of bgv detail objects Background verification details, specified as an array of bgv detail objects.
visas array of government document objects Details of all valid visas held by the employee, specified as an array of government document objects whose document_type is visa.
government_documents array of government document objects All details in the government documents uploaded by the employee, specified as an array of government document objects.
additional_teams array of team objects Details of the additional teams to which an employee belongs, specified as an array of team objects.
additional_managers array of employee model objects Details of additional reporting managers assigned to the employee, specified as an array of employee model objects.
additional_hr_managers array of employee model objects Details of additional HR managers assigned to the employee, specified as an array of employee model objects.
languages array of language objects Languages the employee can speak, specified as an array of language objects.
Attributes of the language object::
id (string): Identifier of the language, auto-generated when the language is added to the Freshteam system.
name (string): Name of the language. created_at (string): Time when the language is added, specified in the UTC format.
updated_at (string): Time when the language name is modified, specified in the UTC format. If the language name is not modified, updated_at is the same as created_at.
deleted (boolean): Specifies whether the language is still a valid language in the Freshteam system. Possible values: true, false

Attributes of the branch object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the branch object, auto-generated when a new branch is configured in the Freshteam system.
created_at string Timestamp of when the branch is created for an organization, specified in the date-time format.
updated_at string Timestamp of when the branch details are last modified, specified in the date-time format.
deleted boolean Specifies whether the branch is still a valid location. An organization can relocate or consolidate branches, in which case the existing branch information is deleted from the Freshteam account but the branch details can still exist in the system as historical data. For such deleted branches, the deleted attribute is set as true.
Possible values: true, false
name string Descriptive identifier of the branch.
street string Address parameter of the branch.
state string Province in which the branch is located.
city string City in which the branch is located.
country_code string Country in which the branch is located, specified as a character code.
zip string Postal code of the region where the branch is located.
time_zone string Time-zone applicable to the branch location.
currency string Three-character valid ISO currency code.
language string Primary language at the branch location.
main_office boolean Specifies whether the branch is the main office at a location.
Possible values: true,false
date_format string Accepted date format at the region where the branch is located.
Possible values: MonthFirst (specifies that the accepted format is MM-DD-YYYY), DateFirst (specifies that the accepted format is DD-MM-YYYY)

Attributes of the team object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the team object, auto-generated when a team is created in the Freshteam system.
created_at string Timestamp of when the team is created, specified in the date-time format.
updated_at string Timestamp of when the team name is last modified, specified in the date-time format.
deleted boolean Specifies whether the team is still a valid grouping in the organization. An organization can merge teams or form sub-teams, in which case the existing team is deleted from the Freshteam account but the team details can still exist in the system as historical data. For such deleted teams, the deleted attribute value is set to true.
Possible values: true, false
name string Descriptive identifier of the team. For example, Corporate Marketing, HR Operations, and so on.

Attributes of the department object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the department object, auto-generated when a new department is created in the Freshteam system.
created_at string Timestamp of when the department is created, specified in the date-time format.
updated_at string Timestamp of when the department name was last modified, specified in the date-time format.
deleted boolean Specifies whether the department still exists in the organization.
Possible values: true, false
name string Meaningful identifier of the department.

Attributes of the level object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of a level object, auto-generated when a level is created in the Freshteam system.
created_at string Timestamp of when the level is created, specified in the date-time format.
updated_at string Timestamp of when the level details are last modified, specified in the date-time format.
deleted boolean Specifies whether the level is still a valid hierarchy in the organization. An organization can merge levels or form new levels, in which case, the existing level is deleted from the Freshteam account but the level details can still exist in the system as historical data. For such deleted levels, the deleted attribute value is set to true.
Possible values: true, false
name string Descriptive identifier of the level. For example, IC2 (Individual contributor - 2), PM3 (Product manager -3) and so on.

Attributes of the role object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of a role object, auto-created when a role is created in the Freshteam system.
created_at string Timestamp of when the role is created, specified in the date-time format.
updated_at string Timestamp of when the role details are last updated, specified in the date-time format.
name string Descriptive identifier of the role. For example, Account Admin, Admin, HR Partner, and so on.
description string Details about the role, mentioning the different privileges provided to a user with the role permission.
default boolean Specifies whether a role is a default role in the Freshteam system or a custom role configured by the organization that uses Freshteam.
Possible values: true, false

Attributes of the dependent object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the dependent object, auto-generated for each set of dependent information saved in the Freshteam system.
name string Full name of the dependent.
relationship string Relationship of the dependent with the employee.
Possible values (enum): Parent, Father, Mother, Spouse, Husband, Wife, Child, Son, Daughter, Sibling, Brother, Sister.
date_of_birth string Date of birth of the dependent.
gender string Gender of the dependent.
Possible values (enum): male, female
deleted boolean Specifies whether the dependent information is deleted from the Freshteam system and exists only as historical data.
Possible values: true, false

Attributes of the employee model object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the employee object, auto-generated when a HR manager, reporting manager, or reportee's information is created in the Freshteam system. This is a valid employee.id value.
city string City, district, town, or any other similar component of the employee’s residential address.
first_name string Business name of the HR, reporting manager, or reportee.
last_name string Last name of the HR, reporting manager, or reportee.
official_email string Official email address of the HR, reporting manager, or reportee.

Attributes of the previous employment object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the previous employment object, auto-generated for each set of previous employment information saved.
company string Name of the employee’s previous organization.
start_date string Date when the employee started work with the previous organization.
end_date string Date till when the employee was with the previous organization.
role string Designation of the employee in the previous organization.
salary_value number Employee’s base salary in the previous organization.
other_salary_components string Compensation components, other than fixed base pay, in the employee’s salary at the previous organization.
description string Job description of the employee’s role in the previous organization.
deleted boolean Specifies whether the employee’s previous organization information still exists in the Freshteam system.
Possible values: true, false
references array of reference object References to people in the employee’s previous organization, who can corroborate the employee’s candidature, specified as an array.

Attributes of the reference object:
name (string): Official name of the person specified as a reference.
number (string): Contact number of the person specified as a reference.

Attributes of the qualification object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the qualification object, auto-generated for each set of education related information saved.
degree string Identifier of the qualification awarded to the employee at the end of a course.
course string Name of the course the employee takes to obtain a qualification.
start_date string Date when the employee starts the course.
end_date string Date till when the course is offered to the employee.
institue_name number Identifier of the institution where the employee undertakes the course.
grade_average string Cumulative average score of the employee, spanning the course period.
pass_out_date string Date when the employee actually completes the course.
deleted boolean Specifies whether the employee’s qualification information still exists in the Freshteam system.
Possible values: true, false
description string Description of the course.

Attributes of the bank account object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the bank account object, auto-generated for each set of bank account information saved.
name_as_per_account string Name of the account holder, according to the bank records.
bank_name string Name of the bank where the employee holds an account.
branch_code string Alphanumeric code of the branch where the employee holds an account, used for banking purposes such as electronic payment transfer.
account_number string Identifier of the employee’s bank account.
deleted boolean Specifies whether the account information is deleted from the Freshteam system and exists only as historical data.
Possible values: true, false

The compensation detail object

Example

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{ "id": 20175, "deleted": false, "current": true, "effective_date": "2019-08-29", "currency": "USD", "annual_amount": 60000, "pay_rate_value": 30000, "eligible_work_hours": 30, "other_components": "Eligible for Sodexo, Insurance, and Travel allowance", "variable_pay": 20, "variable_pay_details": "30 percent of basic", "description": "VPComp1", "reason": { "id": 66, "value": "Completed Intro Period" }, "cost_center": { "id": 51, "value": "Costcenter 1" }, "pay_group": { "id": 19, "value": "Pay Group 1" }, "pay_method": { "id": 16, "value": "Direct Deposit" }, "work_hour_rate": { "id": 59, "value": "Per Day" }, "pay_rate": { "id": 6, "name": "Weekly" }, "pay_schedule": { "id": 3, "name": "Quarterly" }, "variable_pay_frequency": { "id": 6, "name": "Weekly" } }
EXPAND ↓

Attributes

ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the compensation detail object, auto-generated for each set of compensation related information saved.
deleted boolean Specifies whether a specific set of compensation information still exists in the Freshteam system.
Possible values: true, false
current boolean Specifies whether a specific set of compensation information is the employee’s current compensation.
Possible values: true, false
effective_date string Date from when a specific compensation structure is effective.
currency string Currency in which the compensation is payable, specified as a valid three-character ISO currency code.
annual_amount number Annual compensation for the employee.
reason compensation reason object Reason for the existing or modified compensation.

Attributes of the compensation reason object:
id (number): Identifier of the compensation reason object, auto-generated when the reason is configured in the Freshteam system.
value (string): Descriptive identifier of the reason for the compensation. For example, Completion of probation period, Annual appraisal hike, and so on.
description string Summary of the employee’s compensation.
cost_center cost center object Cost group to which the employee belongs.
Employees are grouped into departments, teams, business units, sub-departments, and cost centers. All organization expenditure specific to the employee is borne by the cost center to which the employee belongs.

Attributes of the cost center object:
id (number): Identifier of the cost group to which the employee belongs, auto-generated when the cost center information is configured in the Freshteam system.
value (string): Descriptive identifier of the cost center.
pay_rate_value number Amount payable to the employee for a specific unit of time (identified by pay_rate), in the specified currency.
For example, if an employee is eligible for 250 INR hourly, pay_rate_value is 250, currency is INR, and pay_rate is hourly.
pay_rate pay rate object Unit of time for which the amount identified by pay_rate_value is applicable to the employee.

Attributes of the pay rate object:
id (number): Identifier of the pay rate object, auto-generated when the information is configured in the Freshteam system.
value (string): Descriptive identifier of the duration. For example, hourly, weekly, bi-weekly, and so on.
pay_schedule pay rate object Unit of time for which the amount identified by pay_rate_value is applicable to the employee.

Attributes of the pay rate object:
id (number): Identifier of the pay rate object, auto-generated when the information is configured in the Freshteam system.
value (string): Descriptive identifier of the duration. For example, hourly, weekly, bi-weekly, and so on.
pay_schedule pay rate object Unit of time for which the amount identified by pay_rate_value is applicable to the employee.

Attributes of the pay rate object:
id (number): Identifier of the pay rate object, auto-generated when the information is configured in the Freshteam system.
value (string): Descriptive identifier of the duration. For example, hourly, weekly, bi-weekly, and so on.
pay_group pay group object Payment processing group to which the employee belongs. Employees in an organization can be grouped based on payment factors such as, pay out frequency, annual amount, and so on.

Attributes of the pay group object:
id (number): Identifier of the pay group object, auto-generated when the pay group is configured in the Freshteam system.
value (string): Descriptive identifier of the pay group. For example, C-level.
pay_method pay method object Mode by which the compensation component is disbursed to the employee.

Attributes of the pay method object:
id (number): Identifier of the pay method object, auto-generated when the payment mode is configured in the Freshteam system.
value (string): Descriptive identifier of the payment mode. For example, Paycheck, Cash, Direct Deposit, and so on.
eligible_work_hours number Number of hours the employee typically works, specified in units of day, week, month, or year.
For example, if an employee is eligible to work for 8 hours every day, 8 is the eligible_work_hours value and per day is the work_hour_rate value.
work_hour_rate work hour rate object Mechanism by which the number of hours the employee works is aggregated.

Attributes of the work hour rate object:
id (number): Identifier of the work hour rate object, auto-generated when the aggregation mechanism is configured in the Freshteam system.
value (string): Descriptive identifier of the work hour rate. For example, Per week, Per month, Per day, and so on.
other_components string Additional information on compensation.
pay_factor string Percentage of the actual compensation that is declared as variable pay.
variable_pay number Variable pay amount the employee is eligible for.
variable_pay_frequency variable pay frequency object Frequency at which the organization pays the variable pay to the employee.

Attributes of the variable pay frequency object:
id (number): Identifier of the variable pay frequency object, auto-generated when the information is configured in the Freshteam system.
value (string): Descriptive identifier of the payout frequency. For example, annually, monthly, quarterly, and so on.
variable_pay_details number Additional information pertaining to variable pay.

Attributes of the bonus object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the bonus object, auto-generated for each set of bonus related information saved.
effective_date string Date by when the bonus component is payable.
value string Bonus amount payable to the employee.
currency string Currency in which the bonus is payable, specified as a valid three-character ISO currency code.
bonus_type bonus type object Reason for the bonus payout to the employee.

Attributes of the bonus type object:
id (number): Identifier of the bonus type object, auto-generated when the bonus reason is created in the Freshteam system.
value (string): Descriptive identifier of the bonus reason. For example, New hire bonus, Performance bonus, Transfer bonus, and so on.
position (number): Place of the bonus type in the list of bonus types.
deleted (boolean): Specifies whether the bonus type still exists in the Freshteam system. Possible values: true, false
additional_details string Additional information pertaining to the bonus payout.
deleted boolean Specifies whether a specific bonus component is still valid for the employee.
Possible values: true, false

The stock object

Example

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ "id": 1, "deleted": false, "grant_date": "2019-08-20", "grant_number": 20, "expiration_date": "2019-08-23", "currency": "USD", "total_stock_units": 20, "exercise_price": 70, "exercise_price_discount": 7, "value_per_share": 27, "with_in_range": true, "vesting_type": 2, "effective_date": "2019-08-21", "vesting_period": 20, "vesting_schedule": "weeks", "vesting_rate": 20, "description": "Notes", "grant_reason": { "id": 55, "value": "Promotion" }, "grant_type": { "id": 61, "value": "RSU" }, "pay_rate": { "id": 6, "name": "Weekly" } }
EXPAND ↓

Attributes

ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the stock object, auto-generated for each set of stock grant information saved.
deleted boolean Specifies whether a specific stock grant information is still valid for the employee.
Possible values: true, false
grant_date string Date from when the stock option is valid (effective date).
grant_number number Identifier of grant certificate provided to the employee.
grant_reason stock grant reason object Reason for providing the stock option to the employee.

Attributes of the stock grant reason object:
id (number): Identifier of the stock grant reason object, auto-generated when the reason is created in the Freshteam system.
value (string): Descriptive identifier of the grant reason. For example, Performance appraisal, Promotion, and so on.
position (number): Place of the grant reason in the list of grant reasons.
deleted (boolean): Specifies whether the grant reason is still a valid reason to allocate stocks to employees. Possible values: true, false
grant_type grant type object Type of stock benefit granted to the employee.

Attributes of the grant type object:
id (number): Identifier of the grant type object, auto-generated when the grant type is created in the Freshteam system.
value (string): Descriptive identifier of the grant type. For example, ESOP (options to purchase stocks), RSU (restricted stock units as part of compensation benefits), Phantom stocks, SAR (stock appreciation rights), and so on.
position (number): Place of the grant type in the list of grant types.
deleted (boolean): Specifies whether the grant type is still a valid method to grant stocks to employees. Possible values: true, false
expiration_date string Date by when the stock option provided to the employee expires.
For example, if an employee with ESOP options doesn’t exercise the option to purchase stocks by the expiration_date, the option expires. Similarly, if the employee doesn’t meet the performance standards to realize the restricted stock units allocated, by the expiration_date, the stock allocation expires.
currency string Currency in which the stock can be realized, specified as a valid three-character ISO currency code.
total_stock_units number Total number of stock units granted to the employee as options, restricted stock units, and so on.
exercise_price number Price at which the employee stock option plan states that the employee can purchase stocks.
exercise_price_discount number Discount on the actual market price, that dictates the exercise_price at which the employee can purchase stocks.
value_per_share number Actual market price of a stock unit or a corresponding fair market valuation of the stock unit.
vesting_type number Identifier of the vesting plan defined for the employee. The vesting period (time the employee has to wait to realize the stock grants entirely) depends on the vesting_type.
Possible values: 1 (custom vesting plan), 2 (stock based vesting plan)
effective_date string Start date of the vesting period.
vesting_period string Measure of time associated with vesting_period.
Possible values: years, months, weeks, days, and hours
vesting_schedule number Number of hours the employee typically works, specified in units of day, week, month, or year.
For example, if an employee is eligible to work for 8 hours every day, 8 is the eligible_work_hours value and per day is the work_hour_rate value.
vesting_rate integer Vesting frequency that specifies how often the stocks vest over the vesting_period, starting from the effective_date.
For example, if the vesting frequency in 25 % annually, 25 is the vesting_rate and annually is the pay_rate. It means the employee has to wait for 4 years to vest the stock grants entirely, provided all other vesting criteria (such as performance) are met.
pay_rate pay rate object Unit of time over which the vesting_rate is repeatedly applicable.

Attributes of the pay rate object:
id (number): Identifier of the pay rate object, auto-generated when the information is configured in the Freshteam system.
value (string): Descriptive identifier of the duration. For example, hourly, weekly, bi-weekly, and so on.

Attributes of the award object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the award object, auto-generated when the award is created in the organization's Freshteam system.
name string Name of the award.
awarded_by string Name of the person who awards the employee.
deleted boolean Specifies whether the award category still exists in the system.
Possible values: true, false

Attributes of the certificate object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the certificate object, auto-generated when the certification details are created in the organization's Freshteam system.
name string Name of the certification.
awarded_by string Name of the entity that awards the certification to the employee.
deleted boolean Specifies whether the certification is still a valid certification for the organization.
Possible values: true, false

Attributes of the honor object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the honour object, auto-generated when the honorary title is created in the organization's Freshteam system.
name string Name of the honorary title.
awarded_by string Name of the person who awards the employee with the honorary title.
deleted boolean Specifies whether the honorary title still exists in the system.
Possible values: true, false

Attributes of the license object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the license object, auto-generated when the license category is created in the organization’s Freshteam system.
license_name string Name of the license that the employee holds. For example, Driver’s license.
license_id string Unique license number or identifier associated with an employee’s license.
restrictions string Constraints on the license, if any. For example, the jurisdiction in which the license holds good.
expiry_date string Date till when the license is valid, specified in the date format.
deleted boolean Specifies whether the license category still exists in the system.
Possible values: true, false

Attributes of the bgv details object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the bgv detail object, auto-generated when a type of background verification is created in the organization’s Freshteam system.
status string Background verification status.
Possible values: not_initiated, initiated, in_progress, completed, cancelled
initiation_date string Date when the background verification is initiated for an employee, specified in the date format.
completion_date string Date when the background verification is complete, specified in the date format.
notes string Any additional notes pertaining to the background verification.
deleted boolean Specifies whether the type of background verification still exists in the system.
Possible values: true, false

Attributes of the government document object
ATTRIBUTE TYPE DESCRIPTION
id number Identifier of the government document object, auto-generated when the document’s details are saved in the Freshteam system.
document_name string Descriptive identifier of the document.
number string Unique identifier of the government document, typically printed on the document.
country_code string Country in which the government document is issued, specified as a character code.
issuing_authority string Name of the government authority that has issued the document.
issuing_date boolean Date when the document is issued, specified in the standard date format.
expiry_date string Date till when the document is valid, specified in the standard date format.
deleted boolean whether the government document is still a valid document accepted by the organization.
Possible values: true, false
document_type document type object Details pertaining to the type of document.

Attributes of the document type object:
id (number): Identifier of the document type object, auto-generated when the document type is created in the Freshteam system.
value (string): Descriptive identifier of the document type. For example, visa document.
position (number): Place for the document type in the list of document types.
deleted: Specifies whether the document type is still a valid document type for the organization. Possible values: true, false

onEmployeeUpdate

When an employee record is updated in or deleted from the Freshteam system, the onEmployeeUpdate event is triggered.

Register the onEmployeeUpdate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onEmployeeUpdate": { "handler": "onEmployeeUpdateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onEmployeeUpdateCallback: function(payload) { console.log("Arguments from the onEmployeeUpdate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
{ "timestamp": 1496400354326, "account_id": "15", "domain": "acn.freshteam.com", "event": "onEmployeeUpdate", "region": "US", "data": { "employee": { "id": 17, "created_at": "2020-04-02 07:25:52 UTC", "updated_at": "2020-04-02 07:45:28 UTC", "deleted": false, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_job_category": null, "eeo_company_code": null, "hire_reason": null, "id_card_details": null, "workstation_number": null, "secondary_business_email": null, "work_numbers": [], "nick_name": null, "date_of_birth": null, "marital_status": null, "gender": null, "blood_group": null, "emergency_contacts": [], "social_profiles": [], "address": { "street": "", "state": "", "city": "" }, "phone_numbers": [], "communication_address": { "same_as_residential": false, "communication_street": "", "communication_state": "", "communication_city": "" }, "secondary_last_name": null, "hereditary_last_name": null, "legal_name": null, "previous_name": null, "previous_name_change_date": null, "place_of_birth": null, "im_address": null, "country_of_birth": null, "flsa_required": false, "user_title_id": null, "user_suffix_name_id": null, "user_honorary_suffix_id": null, "user_professional_suffix_id": null, "user_academic_suffix_id": null, "citizenship_status_id": null, "designation": "Regional Manager", "joining_date": null, "internship_end_date": null, "probation_start_date": null, "probation_end_date": null, "job_code": null, "job_exempt": null, "scheduled_weekly_hours": null, "work_hours": null, "start_time": null, "end_time": null, "branch_id": 2, "team_id": 6, "business_unit_id": null, "sub_department_id": null, "department_id": 3, "reporting_to_id": null, "hr_incharge_id": null, "level_id": 6, "shift_id": null, "user_function_id": null, "cost_center_id": null, "employment_end_date": null, "retirement_eligibility_date": null, "expected_retirement_date": null, "actual_retirement_date": null, "termination_date": null, "termination_reason": null, "notice_period": null, "notice_start_date": null, "notice_end_date": null, "retirement_status_id": null, "termination_category_id": null, "custom_fields": { "fwef_cf_str01": "custom_text_1", "uiouoi_cf_str03": { "id": 0, "value": null }, "tryt_cf_str02": null }, "rehire_eligibility": null, "rehire_status": null, "previous_joining_date": null, "previous_exit_date": null, "original_hire_date": null, "avatar_url": null, "first_name": "Alayna", "middle_name": null, "last_name": "Marvin", "employee_id": null, "status": "active", "official_email": "alayna@freshteam.com", "personal_email": "alayna_personal_1@freshteam.com", "confirmed": false, "account_admin": false, "language": "en", "time_zone": "US/Pacific", "employee_type": "contract" }, "associations": { "branch": { "id": 2, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Branch office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": false, "date_format": "MonthFirst" }, "team": { "id": 6, "created_at": "2020-03-23 08:38:43 UTC", "updated_at": "2020-03-23 08:38:43 UTC", "deleted": false, "name": "Field Sales" }, "department": { "id": 3, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Administration" }, "level": { "id": 6, "created_at": "2020-03-23 08:38:43 UTC", "updated_at": "2020-03-23 08:38:43 UTC", "deleted": false, "name": "IC6" }, "roles": [ { "id": 8, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "name": "Employee", "description": "Can view limited set of information of other Employees, request timeoff, view company job postings, and refer a candidate to the Organization.", "default": true } ], "dependents": [], "reportees": [], "incharge_users": [], "prev_employments": [], "qualifications": [], "bank_accounts": [ { "id": 3, "deleted": false, "bank_name": "123Bank", "name_as_per_account": "", "branch_code": "123", "account_number": "123000123" } ], "compensation_details": [ { "id": 9, "deleted": false, "current": true, "effective_date": "2020-04-30", "currency": "AWG", "annual_amount": "123500.0", "pay_rate_value": null, "eligible_work_hours": null, "other_components": null, "variable_pay": null, "variable_pay_details": null, "variable_pay_amount": null, "description": null, "reason_id": null, "pay_method_id": 16, "pay_group_id": null, "work_hour_rate_id": null, "pay_rate_id": null, "pay_schedule_id": 2, "variable_pay_frequency_id": null, "reason": null, "pay_group": null, "pay_method": { "id": 16, "value": "Direct Deposit" }, "work_hour_rate": null, "pay_rate": null, "pay_schedule": { "id": 2, "name": "Semi Annually" }, "variable_pay_frequency": null }, { "id": 10, "deleted": false, "current": true, "effective_date": "2020-04-01", "currency": "AWG", "annual_amount": "123400.0", "pay_rate_value": null, "eligible_work_hours": null, "other_components": null, "variable_pay": null, "variable_pay_details": null, "variable_pay_amount": null, "description": null, "reason_id": null, "pay_method_id": null, "pay_group_id": null, "work_hour_rate_id": null, "pay_rate_id": null, "pay_schedule_id": 2, "variable_pay_frequency_id": null, "reason": null, "pay_group": null, "pay_method": null, "work_hour_rate": null, "pay_rate": null, "pay_schedule": { "id": 2, "name": "Semi Annually" }, "variable_pay_frequency": null } ], "bonuses": [], "stocks": [], "awards": [], "certificates": [], "honors": [], "licenses": [], "background_verification_details": [], "visas": [], "government_documents": [], "additional_teams": [], "additional_managers": [], "additional_hr_managers": [], "languages": [] }, "actor": { "id": 9, "name": "Tyron Dr. Dena", "email": "124498fannie.jones@example.org" } "changes": { "model_changes": { "employee_type": [ "full_time", "contract" ], "team_id": [ 1, 6 ], "branch_id": [ 1, 2 ], "bank_accounts": { "added": [ { "id": 3, "deleted": false, "bank_name": "123Bank", "name_as_per_account": "", "branch_code": "123", "account_number": "123000123" } ] }, "bonuses": "value_encrypted", "compensation_details": { "added": [ { "id": 10, "deleted": false, "current": true, "effective_date": "2020-04-01", "currency": "AWG", "annual_amount": "123400.0", "pay_rate_value": null, "eligible_work_hours": null, "other_components": null, "variable_pay": null, "variable_pay_details": null, "variable_pay_amount": null, "description": null, "reason_id": null, "pay_method_id": null, "pay_group_id": null, "work_hour_rate_id": null, "pay_rate_id": null, "pay_schedule_id": 2, "variable_pay_frequency_id": null } ], "changed": [ [ { "id": 9, "pay_method_id": null, "annual_amount": "123400.0", "effective_date": "Apr-01-2020" }, { "id": 9, "pay_method_id": 16, "annual_amount": "123500.0", "effective_date": "Apr-30-2020" } ] ] }, "personal_email": [ "alayna_personal@freshteam.com", "alayna_personal_1@freshteam.com" ], "custom_fields": { "fwef_cf_str01": [ "custom_text", "custom_text_1" ] } } } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
employee employee object Information pertaining to the employee whose record in the Freshteam system was updated or deleted. The record updation or deletion triggers the onEmployeeUpdate event.
When an employee record is deleted, the employee.deleted value is true.
associations associations object All associated objects of the employee object, that specify additional information pertaining to the employee. This includes information such as the branch, team, and department to which the employee belongs, role of the employee, employee’s dependent information, compensation details, and so on.
actor actor object Information pertaining to the user who updated the employee record.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user; a concatenation of employee.first_name employee.middle_name employee.last_name.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.
changes object Changes that triggered the onEmployeeUpdate event, specified as a JSON object of the following format:
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "model_changes": { //For non-array attributes "<employee.attribute that changed>": ["Old value", "New value"], //For array attributes "<employee.attribute that changed>": { "added": [<array of newly added employee.attribute objects>], "changed": [["Old value1", "New value1"], ["Old value2", "New value2"]] } } }
EXPAND ↓
Note: For array attributes, any value that is deleted is specified in model_changes.changed with the deleted attribute set to true.
onNewHireCreate

When a prospective employee is added to the New Hire Queue, the onNewHireCreate event is triggered.

Register the onNewHireCreate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onNewHireCreate": { "handler": "onNewHireCreateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onNewHireCreateCallback: function(payload) { console.log("Arguments from the onNewHireCreate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
{ "timestamp": 1496400354326, "account_id": "1", "domain": "sample.freshteam.com", "event": "onNewHireCreate", "region": "US", "data": { "newhire": { "id": 19, "created_at": "2020-04-02 07:56:21 UTC", "updated_at": "2020-04-02 07:56:21 UTC", "deleted": false, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_job_category": null, "eeo_company_code": null, "hire_reason": null, "id_card_details": null, "workstation_number": null, "secondary_business_email": null, "work_numbers": null, "nick_name": null, "date_of_birth": null, "marital_status": null, "gender": null, "blood_group": null, "emergency_contacts": null, "social_profiles": null, "address": { }, "phone_numbers": null, "communication_address": { }, "secondary_last_name": null, "heriditary_last_name": null, "legal_name": null, "previous_name": null, "previous_name_change_date": null, "place_of_birth": null, "im_address": null, "country_of_birth": null, "flsa_required": false, "user_title_id": null, "user_suffix_name_id": null, "user_honorary_suffix_id": null, "user_professional_suffix_id": null, "user_academic_suffix_id": null, "citizenship_status_id": null, "designation": "Sample Job Posting", "joining_date": "2020-04-30", "internship_end_date": null, "probation_start_date": null, "probation_end_date": null, "job_code": null, "job_exempt": null, "scheduled_weekly_hours": null, "work_hours": null, "start_time": null, "end_time": null, "branch_id": 1, "team_id": null, "business_unit_id": null, "sub_department_id": null, "department_id": null, "reporting_to_id": null, "hr_incharge_id": null, "level_id": null, "shift_id": null, "user_function_id": null, "cost_center_id": null, "employment_end_date": null, "retirement_eligibility_date": null, "expected_retirement_date": null, "actual_retirement_date": null, "termination_date": null, "termination_reason": null, "notice_period": null, "notice_start_date": null, "notice_end_date": null, "retirement_status_id": null, "termination_category_id": null, "custom_fields": { "fwef_cf_str01": null, "uiouoi_cf_str03": { "id": 0, "value": null }, "tryt_cf_str02": null }, "rehire_eligibility": null, "rehire_status": null, "previous_joining_date": null, "previous_exit_date": null, "original_hire_date": null, "avatar_url": null, "first_name": "Jamar", "middle_name": null, "last_name": "Kristal", "employee_id": null, "status": "hired", "official_email": "lawrence_nicolas@example.com", "personal_email": "lawrence_nicolas@example.com", "confirmed": false, "account_admin": false, "language": "en", "time_zone": "US/Pacific", "introduction": null, "signature": null, "employee_type": "Full time", "hired_on": "2020-04-01 07:56:12 UTC", "no_show": false, "no_show_reason": null }, "associations": { "branch": { "id": 1, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Default - Head office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": true, "date_format": "MonthFirst" }, "roles": [ { "id": 10, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "name": "Onboarding Employee", "description": "Has complete control over his onboarding details and submitdetails for review.", "default": true } ], "dependents": [], "reportees": [], "incharge_users": [], "prev_employments": [], "qualifications": [], "bank_accounts": [], "compensation_details": [], "bonuses": [], "stocks": [], "awards": [], "certificates": [], "honors": [], "licenses": [], "background_verification_details": [], "visas": [], "government_documents": [], "additional_teams": [], "additional_managers": [], "additional_hr_managers": [], "languages": [] }, "actor": { "id": 13, "name": "Sean Dr. Greenfelder", "email": "651497celestina@example.com" } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
newhire newhire object Information pertaining to the prospective employee who is added to the New Hire Queue. The addition triggers the onNewHireCreate event.
associations associations object All associated objects of the newhire object, that specify additional information pertaining to the employee. This includes information such as the branch and role of the new hire, dependent information, compensation details, and so on.
actor actor object Information pertaining to the user who moved a prospective employee to the New Hire Queue.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user; a concatenation of employee.first_name employee.middle_name employee.last_name.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.

Attributes of the newhire object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the newhire object, auto-generated when the corresponding employee record is created in the New Hire queue.
created_at string Timestamp of when the employee record is created, specified in the UTC format.
updated_at string Timestamp of when the new hire information is last updated, specified in the UTC format.
deleted boolean Specifies whether the new hire’s employee record is deleted from the Freshteam system.
For onNewHireCreate, this value is false.
first_name string Business name of the new hire.
middle_name string Middle name of the new hire.
last_name string Last name of the new hire.
official_email string Official email address of the new hire.
employee_id string Employee ID provided by the organization that uses Freshteam.
status string Employment status of the new hire.
Possible values:
  • hired: Prospective employee is added to the New Hire Queue.
  • initiated: Employee onboarding is initiated for the new hire.
  • submitted: Employee onboarding is completed for the new hire.
For onNewHireCreate, this value is hired.
eeo_vetran string Type of vetran recruited based on the Equal Employment Opportunity (EEO) policy of an organization that enables employing veterans from armed forces.
Possible values:
  • Protected vetran: The new hire has served in active duty in the armed forces.
  • Unprotected vetran: The new hire has not served in active duty but was involved in a campaign.
  • I don’t wish to answer
eeo_ethinicity string Ethnicity of the new hire who is recruited based on the EEO policy of the organization.
Possible values:
  • American Indian or Alaska Native (Not Hispanic or Latino)
  • Asian or Indian Subcontinent (Not Hispanic or Latino)
  • Black or African American (Not Hispanic or Latino)
  • Hispanic or Latino
  • Native Hawaiian or Other Pacific Islander (Not Hispanic or Latino)
  • Two or More Races (Not Hispanic or Latino)
  • White (Not Hispanic or Latino)
  • I don’t wish to answer
eeo_disabled string Specifies whether the new hire is recruited based on the EEO policy of the organization that enables employing people with disabilities.
Possible values: Yes, No, I don’t wish to answer
eeo_job_category string EEO job class under which the new hire is recruited.
Possible values:
  • Executive/Senior Level Managers
  • First/Mid Level Managers
  • Professionals
  • Technicians
  • Sales Workers
  • Administrative/Support Workers
  • Craft Workers
  • Operatives
  • Laborers and Helpers
  • Service Workers
eeo_company_code string EEO company code that the EEO commission assigns to an organization.
hire_reason string Reason the interview panel provides for hiring the new hire.
id_card_details string Number or code associated with the ID card provided to the new hire when the new hire joins the organization.
work_numbers array of work number objects Official phone numbers to be assigned to the new hire after the new hire joins the organization, specified as an array of work number objects.
Attributes of the work number object:
name (string): Type of phone number. Possible values: Work, Office Ext., Mobile, Others
number (string): Official contact number of the employee.
workstation_number string Work desk number to be assigned to the new hire after the new hire joins the organization.
secondary_business_email string Alternate work contact information for the new hire.
nick_name string Alternate display name for the new hire, in the Freshteam system.
date_of_birth string Birth date of the new hire.
marital_status string Marital status of the new hire.
Possible values: single, married
gender string Gender of the new hire.
Possible values: male, female
blood_group string Blood group of the new hire.
Possible values: A−, B−, O−, B+, O+, A+, A1+, A1B-, AB+, AB-, A1B+, A2+, A2B-, A2B+, A1-
emergency_contacts array of emergency contact objects Details of the people to be contacted if there is an emergency situation, specified as an array of emergency contact objects.
Attributes of the emergency contact object:
name (string)
relationship (string): Possible values: Parent, Father, Mother, Spouse, Husband, Wife, Child, Son, Daughter, Sibling, Brother, Sister
contant_number (string)
address (string)
social_profiles array of objects List of all social platforms in which the new hire is available, specified as a social_profile array of objects.
Attributes of the array object:
name (string): Name of the social medium.
url (string): Link to the new hire's social medium handle.
address address object Residential address of the new hire.
Attributes of the address object:
street (string)
state (string)
city (string)
country_code (string)
zip_code (string)
communication_address communication address object Address to which all official communication is sent.
Attributes of the communication address object:
communication_street (string)
communication_city (string)
communication_state (string)
communication_country_code (string)
communication_zip_code (string)
same_as_residential (boolean): The attribute is part of the employee object only if the attribute value is false.
designation string Job title of the new hire.
phone_numbers array of phone number objects Contact numbers of the new hire, specified as an array of phone number objects.
Attributes of the phone number object::
name (string): Type of phone number. Possible values: Home, Main, Mobile, Others
number (string): Personal contact number of the employee.
secondary_last_name string Second surname of the new hire, if the new hire has a composite surname.
hereditary_last_name string Family name part of the new hire’s surname, if the new hire has a composite surname.
legal_name string Registered name of the new hire.
previous_name string Previous name of the new hire, if the new hire has changed the official name.
previous_name_change_date string Date from when the new hire’s new name is official, as per the legal records.
place_of_birth string City where the new hire was born.
im_address string Official instant messenger address of the new hire.
country_of_birth string Country where the new hire was born.
flsa_required boolean Specifies whether the new hire requires legal protection under the Fair Labour Standards Act (FLSA).
Possible values: true, false
job_code string Job code of the new hire, as specified in FLSA.
job_exempt boolean Specifies whether the job for which the new hire is recruited is exempted from protection offered by FLSA.
Possible values: Exempted, Not exempted
user_title_id integer Identifier of the title associated with the new hire.
When an organization configures the list of possible titles in the Freshteam system, an id is auto-generated for each title. For example, if the organization configures Mr. and Ms. as the possible titles, the corresponding auto-generated ids can be 12 and 13. When a new hire’s information is saved, if Mr. is chosen as the Title of the new hire, user_title_id is 12.
user_suffix_name_id integer Identifier of the name suffix associated with the new hire.
When an organization configures the list of possible name suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures Jr. and Sr. as the possible suffixes, the corresponding auto-generated ids can be 14 and 15. When a new hire’s information is saved, if Jr. is chosen as the Suffix Name of the new hire, user_suffix_name_id is 14.
user_honorary_suffix_id integer Identifier of the honorary title bestowed to the new hire.
When an organization configures the list of possible honorary titles in the Freshteam system, an id is auto-generated for each title. For example, if the organization configures OBE and MBE as the possible honours, the corresponding auto-generated ids can be 16 and 17. When a new hire’s information is saved, if OBE is chosen as the Honorary Title of the new hire, user_honorary_suffix_id is 16.
user_professional_suffix_id integer Identifier of the professional suffix associated with the new hire.
When an organization configures the list of possible professional suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures CFA and CPA as the possible suffixes, the corresponding auto-generated ids can be 18 and 19. When a new hire’s information is saved, if CPA is chosen as the Professional Suffix of the new hire, user_professional_suffix_id is 18.
user_academic_suffix_id integer Identifier of the academic qualification, which can be specified as a suffix, associated with the new hire.
When an organization configures the list of possible academic suffixes in the Freshteam system, an id is auto-generated for each suffix. For example, if the organization configures M.S and Ph.D as the possible suffixes, the corresponding auto-generated ids can be 20 and 21. When a new hire’s information is saved, if M.S is chosen as the Academic Suffix of the new hire, user_academic_suffix_id is 20.
citizenship_status_id integer Identifier of the new hire’s citizenship status.
When an organization configures the list of possible citizenship statuses in the Freshteam system, an id is auto-generated for each status. For example, if the organization configures Naturalised and By Birth as the possible statuses, the corresponding auto-generated ids can be 22 and 23. WWhen a new hire’s information is saved, if Naturalised is chosen as the Citizenship Status of the new hire, citizenship_status_id is 22.
joining_date string Date when the new hire will join the organization, specified in the YYYY-MM-DD format.
internship_end_date string Date when the new hire’s internship ends. This value is null for new hires who are not interns.
probation_start_date string Date when the new hire’s probation period will start, after the new hire joins the organization, specified in the YYYY-MM-DD format.
probation_end_date string Date when the new hire’s probation period will end, after the new hire joins the organization, specified in the YYYY-MM-DD format.
scheduled_weekly_hours integer Number of hours scheduled for the new hire’s job position. If weekly hours are scheduled for a position, all work beyond the scheduled hours is considered for over-time.
work_hours integer Number of hours the new hire is expected to work.
start_time string In a day, the typical work starting time of the new hire, set by the organization.
end_time string In a day, the typical work ending time of the new hire, set by the organization.
branch_id string Identifier of the branch to which the new hire will belong, after joining the organization. This is the branch.id value that is auto-generated when the branch’s information is configured in Freshteam.
team_id string Identifier of the primary work group to which the new hire will belong, after joining the organization. This is the team.id value that is auto-generated when the team’s information is configured in Freshteam.
business_unit_id string Identifier of the business function to which the new hire will belong, after joining the organization.
When a business unit is configured in Freshteam, a business unit object is created and an id is auto-generated. business_unit_id is this id value. The name attribute of the object identifies the business units. For example, DevOps.
department_id string Identifier of the department (job role) to which the new hire will belong, after joining the organization. This is the department.id value that is auto-generated when the department’s information is configured in Freshteam.
sub_department_id string Identifier of the subcategory of the job role to which the new hire will belong after joining the organization. When a sub-department is configured in Freshteam, a sub-department object is created and an id is auto-generated. sub_department_id is this id value. The name attribute of the object identifies the sub-department.
reporting_to_id string Identifier of the person assigned as the reporting manager of the new hire. This is the employee.id value that is auto-generated when the reporting manager’s employee record is stored in Freshteam.
hr_incharge_id string Identifier of the person assigned as the HR incharge of the new hire. This is the employee.id value that is auto-generated when the HR incharge’s employee record is stored in Freshteam.
level_id string Identifier of the job band to which the new hire will belong, after joining the organization. This is the level.id value that is auto-generated when the job band is configured in Freshteam.
shift_id string Identifier of the shift to which the new hire will belong, after joining the organization.
When a shift is configured in Freshteam, a shift object is created and an id is auto-generated. shift_id is this id value. The name attribute of the object identifies the shift. For example, Day shift, EMEA shift, and so on.
user_function_id string Identifier of the specific function the new hire will perform as part of a team.
When a user function is configured in Freshteam, a user function object is created and an id is auto-generated. user_function_id is this id value. The name attribute of the object identifies the user function. For example, GTM, design, and so on.
cost_center_id string Identifier of the cost group to which the new hire will belong.
Employees are grouped into departments, teams, business units, sub-departments, and cost centers. All organization expenditure specific to the employee is borne by the cost center to which the employee belongs. When a cost centre is configured in Freshteam, a cost centre object is created and an id is auto-generated. cost_center_id is this id value.
employment_end_date string Date by when the new hire’s offer of employment will cease, specified in the YYYY-MM-DD format. If a notice period is set for an organization, this value is auto-populated based on the notice period, after the new hire joins the organization.
retirement_eligibility_date string Date after which the new hire is eligible to opt for retirement, specified in the YYYY-MM-DD format.
expected_retirement_date string Date by when the new hire is expected to retire, specified in the YYYY-MM-DD format.
actual_retirement_date string Actual date when the employee retires, specified in the YYYY-MM-DD format. For onNewHireCreate, this value is null.
termination_date string Date when the employee leaves the organization, specified in the YYYY-MM-DD format. For onNewHireCreate, this value is null.
termination_reason string Reason stating why the employee leaves the organization, specified by the person who updates the employee record. For onNewHireCreate, this value is null.
termination_category_id integer Identifier of the termination category under which the employee ceases to work for the organization.
When a termination category is configured in Freshteam, a termination category object is created and an id is auto-generated. termination_category_id is this id value. The value attribute of the object identifies the category. For example, Resignation, End of Contract, Involuntary, and so on.
notice_period string Duration the employee has to serve as notice period.
notice_start_date string Starting date of the notice period, updated after the employee’s termination is approved. For onNewHireCreate, this value is null.
notice_end_date string Ending date of the notice period, updated after the employee’s termination is approved. For onNewHireCreate, this value is null.
retirement_status_id integer Identifier of the retirement status associated with the employee.
When a retirement status is configured in Freshteam, a field option object is created and an id is auto-generated. retirement_status_id is this id value. The value attribute of the object identifies the status. For example, Retired, Voluntary retirement process, and so on.
rehire_eligibility boolean Specifies whether the employee, whose services have ended, is eligible to be hired in the future. For onNewHireCreate, this value is null.
rehire_status boolean Specifies whether the new hire is a rehire in the organization.
previous_joining_date string Date when the new hire started services, in the new hire’s previous stint with the organization, specified in the YYYY-MM-DD format.
previous_exit_date string Date when the new hire’s offer of employment ceased, in the new hire’s previous stint with the organization, specified in the YYYY-MM-DD format.
original_hire_date string Date when the new hire’s rehiring is finalized and offer of employment rolled out, specified in the YYYY-MM-DD format.
custom_fields object The organization that uses Freshteam can configure custom fields to obtain additional employee information. The custom_fields attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.
avatar_url string Location of the image file that is used to populate the avatar of the new hire, in the new hire’s personal information page.
personal_email string Personal email address of the new hire.
employee_type string Employment terms that apply to the new hire. For example, Full Time, Part Time, Contract, Internship, Temporary, Seasonal, Volunteer, and so on.
confirmed boolean Specifies whether the new hire has activated the Freshteam log in, by verification through the activation mail sent to the new hire’s email. For onNewHireCreate, this value is false.
account_admin boolean Specifies whether the role associated with the new hire is Account Admin. Possible values: true, false
language string Primary language of the branch to which the new hire is associated.
time_zone string Time-zone applicable to the branch to which the new hire is associated.
hired_on string Date when the new hire’s hiring is finalized and offer of employment rolled out, specified in the YYYY-MM-DD format.
no_show boolean Specifies whether the new hire joined the organization after accepting the offer of employment. For onNewHireCreate, this value is false.
no_show_reason string Reason why the new hire did not join the organization after accepting the offer of employment. For onNewHireCreate, this value is null.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
branch branch object Details of the branch to which the new hire belongs.
team team object Details of the primary employee group (team) to which the new hire belongs.
department department object Details of the department to which the new hire belongs.
level level object Details of the job band to which the new hire belongs.
roles array of role objects All roles associated with the new hire, specified as an array of role objects.
An employee’s access to different entities in the Freshteam system is based on the roles associated with the employee. Role permissions define the access privileges an employee is entitled to. Each role comes with a predefined set of privileges. For more information on roles, see Understanding user roles in Freshteam.
dependents array of dependent objects All details of an new hire’s dependents, specified as an array of dependent objects.
reportees array of employee model objects Details of all reportees (employees whose employee.reporting_to_id is the newhire.id value of the new hire who was added to the New Hire Queue), specified as an array of employee model objects.
incharge_users array of employee model objects Details of the HR incharge and reporting manager of the new hire, specified as an array of employee model objects.
prev_employments array of previous employment objects All details of the new hire’s previous employment positions, specified as an array of previous employment objects.
qualifications array of qualification objects All details of the new hire’s education, specified as an array of qualification objects.
bank_accounts array of bank account objects All details of the new hire’s bank accounts, specified as an array of bank account objects.
compensation_details array of compensation detail objects All details of the new hire’s compensation, specified as an array of compensation detail objects.
bonuses array of bonus objects All details of the new hire’s various bonuses, specified as an array of bonus objects.
stocks array of stock objects All details of the new hire’s stock grant options, specified as an array of stock objects.
awards array of award objects All awards associated with the new hire, specified as an array of award objects.
certificates array of certificate objects All certificates awarded to the new hire, specified as an array of certificate objects.
honors array of honor objects All honorary titles associated with the new hire, specified as an array of honor objects.
licenses array of license objects Information from all license documents, specified as an array of license objects.
background_verification_details array of bgv detail objects Background verification details, specified as an array of bgv detail objects.
visas array of government document objects Details of all valid visas held by the new hire, specified as an array of government document objects whose document_type is visa.
government_documents array of government document objects All details in the government documents uploaded by the new hire, specified as an array of government document objects.
additional_teams array of team objects Details of the additional teams to which the new hire belongs, specified as an array of team objects.
additional_managers array of employee model objects Details of additional reporting managers assigned to the new hire, specified as an array of employee model objects.
additional_hr_managers array of employee model objects Details of additional HR managers assigned to the new hire, specified as an array of employee model objects.
languages array of language objects Languages the new hire can speak, specified as an array of language objects.
Attributes of the language object::
id (string): Identifier of the language, auto-generated when the language is added to the Freshteam system.
name (string): Name of the language. created_at (string): Time when the language is added, specified in the UTC format.
updated_at (string): Time when the language name is modified, specified in the UTC format. If the language name is not modified, updated_at is the same as created_at.
deleted (boolean): Specifies whether the language is still a valid language in the Freshteam system. Possible values: true, false
onNewHireUpdate

When a prospective employee’s profile in the New Hire Queue is edited and saved or deleted, the onNewHireUpdate event is triggered.

Register the onNewHireUpdate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onNewHireUpdate": { "handler": "onNewHireUpdateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onNewHireUpdateCallback: function(payload) { console.log("Arguments from the onNewHireUpdate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onNewHireUpdate", "region": "US", "data": { "newhire": { "id": 19, "created_at": "2020-04-02 07:56:21 UTC", "updated_at": "2020-04-02 07:56:21 UTC", "deleted": false, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_job_category": null, "eeo_company_code": null, "hire_reason": null, "id_card_details": null, "workstation_number": null, "secondary_business_email": null, "work_numbers": null, "nick_name": null, "date_of_birth": null, "marital_status": null, "gender": null, "blood_group": null, "emergency_contacts": null, "social_profiles": null, "address": { }, "phone_numbers": null, "communication_address": { }, "secondary_last_name": null, "heriditary_last_name": null, "legal_name": null, "previous_name": null, "previous_name_change_date": null, "place_of_birth": null, "im_address": null, "country_of_birth": null, "flsa_required": false, "user_title_id": null, "user_suffix_name_id": null, "user_honorary_suffix_id": null, "user_professional_suffix_id": null, "user_academic_suffix_id": null, "citizenship_status_id": null, "designation": "Sample Job Posting", "joining_date": "2020-04-30", "internship_end_date": null, "probation_start_date": null, "probation_end_date": null, "job_code": null, "job_exempt": null, "scheduled_weekly_hours": null, "work_hours": null, "start_time": null, "end_time": null, "branch_id": 1, "team_id": null, "business_unit_id": null, "sub_department_id": null, "department_id": null, "reporting_to_id": null, "hr_incharge_id": null, "level_id": null, "shift_id": null, "user_function_id": null, "cost_center_id": null, "employment_end_date": null, "retirement_eligibility_date": null, "expected_retirement_date": null, "actual_retirement_date": null, "termination_date": null, "termination_reason": null, "notice_period": null, "notice_start_date": null, "notice_end_date": null, "retirement_status_id": null, "termination_category_id": null, "custom_fields": { "fwef_cf_str01": "custom_text_1", "uiouoi_cf_str03": { "id": 0, "value": null }, "tryt_cf_str02": null }, "rehire_eligibility": null, "rehire_status": null, "previous_joining_date": null, "previous_exit_date": null, "original_hire_date": null, "avatar_url": null, "first_name": "Jamar", "middle_name": null, "last_name": "Kristal", "employee_id": null, "status": "initiated", "official_email": "lawrence_nicolas@example.com", "personal_email": "lawrence_nicolas@example.com", "confirmed": false, "account_admin": false, "language": "en", "time_zone": "US/Pacific", "introduction": null, "signature": null, "user_category": "onboarding", "employee_type": "full_time", "hired_on": "2020-04-01 07:56:12 UTC", "no_show": true, "no_show_reason": "sample reason" }, "associations": { "branch": { "id": 2, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Branch office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": false, "date_format": "MonthFirst" }, "team": { "id": 6, "created_at": "2020-03-23 08:38:43 UTC", "updated_at": "2020-03-23 08:38:43 UTC", "deleted": false, "name": "Field Sales" }, "department": { "id": 3, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "deleted": false, "name": "Administration" }, "level": { "id": 6, "created_at": "2020-03-23 08:38:43 UTC", "updated_at": "2020-03-23 08:38:43 UTC", "deleted": false, "name": "IC6" }, "roles": [ { "id": 8, "created_at": "2020-03-23 08:38:42 UTC", "updated_at": "2020-03-23 08:38:42 UTC", "name": "Employee", "description": "Can View limited set of information of other Employees, Request timeoff, View company job postings and Refer a candidate to an Organisation.", "default": true } ], "dependents": [ ], "reportees": [ ], "incharge_users": [ ], "prev_employments": [ ], "qualifications": [ ], "bank_accounts": [ { "id": 3, "deleted": false, "bank_name": "123Bank", "name_as_per_account": "", "branch_code": "123", "account_number": "123000123" } ], "compensation_details": [ { "id": 9, "deleted": false, "current": true, "effective_date": "2020-04-30", "currency": "AWG", "annual_amount": "123500.0", "pay_rate_value": null, "eligible_work_hours": null, "other_components": null, "variable_pay": null, "variable_pay_details": null, "variable_pay_amount": null, "description": null, "reason_id": null, "pay_method_id": 16, "pay_group_id": null, "work_hour_rate_id": null, "pay_rate_id": null, "pay_schedule_id": 2, "variable_pay_frequency_id": null, "reason": null, "pay_group": null, "pay_method": { "id": 16, "value": "Direct Deposit" }, "work_hour_rate": null, "pay_rate": null, "pay_schedule": { "id": 2, "name": "Semi Annually" }, "variable_pay_frequency": null }, { "id": 10, "deleted": false, "current": true, "effective_date": "2020-04-01", "currency": "AWG", "annual_amount": "123400.0", "pay_rate_value": null, "eligible_work_hours": null, "other_components": null, "variable_pay": null, "variable_pay_details": null, "variable_pay_amount": null, "description": null, "reason_id": null, "pay_method_id": null, "pay_group_id": null, "work_hour_rate_id": null, "pay_rate_id": null, "pay_schedule_id": 2, "variable_pay_frequency_id": null, "reason": null, "pay_group": null, "pay_method": null, "work_hour_rate": null, "pay_rate": null, "pay_schedule": { "id": 2, "name": "Semi Annually" }, "variable_pay_frequency": null } ], "bonuses": [ ], "stocks": [ ], "awards": [ ], "certificates": [ ], "honors": [ ], "licenses": [ ], "background_verification_details": [ ], "visas": [ ], "government_documents": [ ], "additional_teams": [ ], "additional_managers": [ ], "additional_hr_managers": [ ], "languages": [ ] }, "actor": { "id": 9, "name": "Tyron Dr. Dena", "email": "124498fannie.jones@example.org" }, "changes": { "model_changes": { "status": [ "hired", "initiated" ], "no_show": [ false, true ], "no_show_reason": [ null, "sample reason" ], "custom_fields": { "fwef_cf_str01": [ "custom_text", "custom_text_1" ] } } } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
newhire newhire object Information pertaining to the new hire whose record in the Freshteam system is updated or deleted. The record updation or deletion triggers the onNewHireUpdate event.
When a record is deleted, the newhire.deleted value is true.
associations associations object All associated objects of the newhire object, that specify additional information pertaining to the employee. This includes information such as the branch and role of the new hire, dependent information, compensation details, and so on.
actor actor object Information pertaining to the user who updated the new hire’s record.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.
changes object Changes that triggered the onNewHireUpdate event, specified as a JSON object of the following format:
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "model_changes": { //For non-array attributes "<newhire.attribute that changed>": ["Old value", "New value"], //For array attributes "<newhire.attribute that changed>": { "added": [<array of newly added newhire.attribute objects>], "changed": [["Old value1", "New value1"], ["Old value2", "New value2"]] } } }
EXPAND ↓
Note: For array attributes, any value that is deleted is specified in model_changes.changed with the deleted attribute set to true.
onJobPostingCreate

When a job posting is created in the Freshteam system and saved for later perusal or published, the onJobPostingCreate event is triggered.

Register the onJobPostingCreate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onJobPostingCreate": { "handler": "onJobPostingCreateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onJobPostingCreateCallback: function(payload) { console.log("Arguments from the onJobPostingCreate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onJobPostingCreate", "region": "US", "data": { "jobposting": { "id": 1, "created_at": "2020-08-06 13:34:34 UTC", "updated_at": "2020-08-07 12:59:19 UTC", "deleted": false, "title": "Sample Job Posting", "description": "<p style=\"text-align: center;\">As a sales team member, you’ll be on the fore-front to uncover the market potential through generating leads, understanding the account opportunity, qualifying and closing sales and more importantly keep the business informed about new product or services that may require from time to time.</p>\n <p style=\"text-align: center;\">&nbsp;</p>\n <p>&nbsp;</p>", "status": "published", "salary": { "min": 80000, "max": 100000, "currency": "USD" }, "applicant_access_type": "open", "remote": false, "show_pursue_as_career": false, "closing_date": "2020-11-20", "applicant_apply_link": "http://sample.freshteam.com/jobs/zfJ7u-Xsyj73/sample-job-posting", "experience": "Executive/President", "type": "full_time" }, "associations": { "branch": { "id": 2, "created_at": "2020-08-06 13:34:06 UTC", "updated_at": "2020-08-06 13:34:06 UTC", "deleted": false, "name": "Branch office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": false, "date_format": "MonthFirst" }, "department": { "id": 4, "created_at": "2020-08-06 13:34:06 UTC", "updated_at": "2020-08-06 13:34:06 UTC", "deleted": false, "name": "Sales" }, "custom_field_values": {}, "skills": [], "remote_branches": [], "requisitions": [ { "id": 1, "deleted": false, "title": "Default Requisition", "recruiters": [ { "id": 1, "first_name": "John", "last_name": "Smith", "official_email": "john@freshteam.com" } ], "hiring_managers": [], "panel_members": [] } ] }, "actor": { "id": 9, "name": "Tyron Dr. Dena", "email": "124498fannie.jones@example.org" } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
jobposting jobposting object Information pertaining to the job posting that is created in the Freshteam system. Saving or publishing the job posting, triggers the onJobPostingCreate event.
associations associations object All associated objects of the jobposting object, that specify additional information about the job posting. This includes information on the branch and department that has the job requirement, job requisition linked to the posting, expected skills defined for the job, and so on.
actor actor object Information pertaining to the user who created the job posting.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.

Attributes of the jobposting object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the jobposting object, auto-generated when the job posting is saved or published in the Freshteam system.
created_at string Timestamp of when the job posting is created, specified in the UTC format.
updated_at string Timestamp of when the job posting information is last updated, specified in the UTC format.
For onJobPostingCreate, this value is the same as the created_at value.
deleted boolean Specifies whether a job posting is deleted from the Freshteam system.
For onJobPostingCreate and onJobPostingUpdate triggered by record updation, this value is false.
For onJobPostingUpdate triggered by record deletion, this value is true.
title string Job title that specifies the profile for which the organization is hiring.
description string Job description (in HTML format) that provides a brief of the role, requirements expected from the candidates, and responsibilities that the profile entails.
status string Status of the job posting.
Possible values:
  • draft:: The job posting is saved for later use but not published.
  • published: The job posting is published to the organization’s career and employee portals.
  • internal: The job posting is published to the organization’s employee portal.
  • private: The job posting is visible only to the hiring teams and users with admin permissions.
  • on-hold: The job posting is frozen and new candidates cannot be added for the posting.
  • closed: The job requirement is met and the posting is closed.
salary object Salary band defined for the job role.
Attributes of the object:
currency (string): Currency in which the salary is payable, specified as a valid three-character ISO currency code.
min (integer): Minimum salary payable.
max (integer): Maximum salary payable.
applicant_access_type string Specifies the access restrictions to view applicant information. For onJobPostingCreate, this value is open.
Possible values:
  • open: Default access - all recruiters, hiring managers, and panel members assigned to the job posting can view all information pertaining to all applicants.
  • closed: Restricted access - all recruiters can view all information pertaining to all applicants. Hiring managers and panel members can view applicant information only if they are added as followers of the applicant (candidate).
remote boolean Specifies whether the job posting is for a remote job.
Possible values: true, false
show_persue_as_career boolean Specifies whether the employees within the organization can apply for the job.
Possible values: true, false
closing_date string Date by which the job requisition associated with the job posting should be filled.
applicant_apply_link string URL using which the applicants can respond to the job posting, when the job posting is shared through various channels.
experience string Requisite experience level for the job role.
Possible values (for the default field available in Freshteam):
  • Internship
  • Entry level
  • Associate
  • Mid-Senior level
  • Director/Vice-president
  • Executive/President
type string Employment terms that apply to the job role. For example, Full Time, Part Time, Contract, Internship, Temporary, Seasonal, Volunteer, and so on.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
branch branch object Details of the branch specified as the job location, when the job posting is created or updated. If a job location is not specified or the job is marked as a remote job, the branch attribute contains details of the default branch.
department department object Details of the department to which the job role belongs.
custom_field_values object The organization that uses Freshteam can configure custom fields to specify more information about a job. The custom_field_values attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.
skills array of strings Skills expected from candidates who apply for the job role.
remote_branches array of strings All preferred locations that are used when the job posting is listed on external job boards.
requisitions array of requisition objects All job requisitions associated with the job posting.
For onJobPostingCreate, this attribute contains details pertaining to the default requisition.
Attributes of the requisition object:
id (integer): Identifier of the requisition object, auto-generated when a job requisition is created in the Freshteam system.
deleted (boolean): Specifies whether the job requisition is deleted from the Freshteam system. Possible values: true, false
title (string): Title of the job requisition, indicating the job role for which the requisition is created.
recruiters (array of employee model objects): Details of the recruiters assigned to the requisition. For onJobPostingCreate, this attribute contains the details of the employee who created the job posting.
hiring_managers (array of employee model objects): Details of the employees assigned as hiring managers, in the job posting. For onJobPostingCreate, this attribute is an empty array.
panel_members (array of employee model objects): Details of the employees assigned as the interview panel members, in the job posting. For onJobPostingCreate, this attribute contains the details of the employee who created the job posting.
onJobPostingUpdate

When a job posting is updated or deleted from the Freshteam system, the onJobPostingUpdate event is triggered.

Register the onJobPostingUpdate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onJobPostingUpdate": { "handler": "onJobPostingUpdateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onJobPostingUpdateCallback: function(payload) { console.log("Arguments from the onJobPostingUpdate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onJobPostingUpdate", "region": "US", "data": { "jobposting": { "id": 1, "created_at": "2020-08-06 13:34:34 UTC", "updated_at": "2020-08-07 12:59:19 UTC", "deleted": false, "title": "Sample Job Posting", "description": "<p style=\"text-align: center;\">Job description in HTML format</p>\n <p style=\"text-align: center;\">&nbsp;</p>\n <p>&nbsp;</p>", "status": "published", "salary": { "min": 80000, "max": 100000, "currency": "USD" }, "applicant_access_type": "open", "remote": false, "show_pursue_as_career": false, "closing_date": "2020-11-20", "applicant_apply_link": "http://sample.freshteam.com/jobs/zfJ7u-Xsyj73/sample-job-posting", "experience": "Executive/President", "type": "full_time" }, "associations": { "branch": { "id": 2, "created_at": "2020-08-06 13:34:06 UTC", "updated_at": "2020-08-06 13:34:06 UTC", "deleted": false, "name": "Branch office", "state": null, "city": "San Francisco", "country_code": "US", "zip": null, "time_zone": "US/Pacific", "currency": "USD", "language": null, "main_office": false, "date_format": "MonthFirst" }, "department": { "id": 4, "created_at": "2020-08-06 13:34:06 UTC", "updated_at": "2020-08-06 13:34:06 UTC", "deleted": false, "name": "Sales" }, "custom_field_values": { }, "skills": [], "remote_branches": [], "requisitions": [ { "id": 1, "deleted": false, "title": "Default Requisition", "recruiters": [ { "id": 1, "first_name": "John", "last_name": "Smith", "official_email": "john@freshteam.com" } ], "hiring_managers": [], "panel_members": [] } ] }, "actor": { "id": 9, "name": "Tyron Dr. Dena", "email": "124498fannie.jones@example.org" }, "changes": { "model_changes": { "experience": [ "Director/Vice-President", "Executive/President" ] } } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
jobposting jobposting object Information pertaining to the job posting that is updated or deleted from the Freshteam system. The posting’s updation or deletion triggers the onJobPostingUpdate event.
When a job posting is deleted, the jobposting.deleted value is true.
associations associations object All associated objects of the job posting object, that specify additional information pertaining to the job posting. This includes information on the branch and department that has the job requirement, job requisition linked to the posting, expected skills defined for the job, and so on.
actor actor object Information pertaining to the user who updated or deleted the job posting.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.
changes object Changes that triggered the onJobPostingUpdate event, specified as a JSON object of the following format:
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "model_changes": { //For non-array attributes "<jobposting.attribute that changed>": ["Old value", "New value"], //For array attributes "<jobposting.attribute that changed>": { "added": [<array of newly added jobposting.attribute objects>], "changed": [["Old value1", "New value1"], ["Old value2", "New value2"]] } } }
EXPAND ↓
Note: For array attributes, any value that is deleted is specified in model_changes.changed with the deleted attribute set to true.
onTimeOffCreate

When a time-off request is raised in the Freshteam system, the onTimeOffCreate event is triggered.

Register the onTimeOffCreate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onTimeOffCreate": { "handler": "onTimeOffCreateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onTimeOffCreateCallback: function(payload) { console.log("Arguments from the onTimeOffCreate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{ "timestamp": 1496400354326, "account_id": "1", "domain": "sample.freshteam.com", "event": "onTimeOffCreate", "region": "US", "data": { "timeoff": { "id": 10, "created_at": "2020-08-17 07:51:52 UTC", "updated_at": "2020-08-17 07:51:52 UTC", "user_id": 1, "start_date": "2020-08-27", "end_date": "2020-08-27", "status": "pending", "leave_units": 1, "optional_leave_units": null, "leave_type_id": 2, "status_comments": "", "approved_by_id": null, "applied_by_id": 1, "cancelled_by_id": null, "rejected_by_id": null, "comments": "Personal work", "rejected_at": null, "cancelled_at": null, "cancelled_due_to_exit": false }, "associations": { "attachment": { "id": 4, "content_file_name": "sample.docx", "content_file_size": 7448, "description": "timeoff", "url": "files.freshteam.com/docs/sample.docx" }, "leave_type": { "id": 2, "deleted": false, "name": "Earned", "description": "Earned Leave", "applicable_for": "all", "default": true, "auto_approve": false, "auto_approve_after": null, "auto_approve_limit": null, "marital_status": "all" }, "applied_by": { "id": 1, "first_name": "John", "last_name": "Keith", "official_email": "john@freshteam.com" }, "user": { "id": 1, "first_name": "John", "last_name": "Keith", "official_email": "john@freshteam.com" } }, "actor": { "id": 1, "name": "John Keith", "email": "john@freshteam.com" } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
timeoff timeoff object Information pertaining to the time-off request that is raised in the Freshteam system. The time-off application triggers the onTimeOffCreate event.
associations associations object All associated objects of the timeoff object, that provide additional information pertaining to the time-off request. This includes the documents attached to the request, information on the time-off type and applicant, and so on.
actor actor object Information pertaining to the user who raises the time-off request.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.

Attributes of the timeoff object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the timeoff object, auto-generated when a time-off is applied through the Freshteam system.
created_at string Timestamp of when the timeoff object is created, specified in the UTC format.
updated_at string Timestamp of when the time-off information is last updated, specified in the UTC format.
For onTimeOffCreate, this value is the same as the created_at value.
user_id integer Identifier of the user for whom the request is raised. This is a valid employee.id value of an employee record.
start_date string Starting date of the applicant’s absence, specified in the time-off request.
end_date string Ending date of the applicant’s absence, specified in the time-off request.
status string Status of the time-off request.
Possible values: pending, approved, declined, cancelled
For onTimeOffCreate, this value is pending.
leave_units integer Number of days of time-off applied through the time-off request, auto-generated considering the organization’s work and holiday calendars and the time-off request’s start_date and end_date.
optional_leave_units integer Number of days of optional holidays that falls within the time-off request period.
leave_type_id integer Identifier of the time-off type under which the time-off request is raised.
When an organization configures the list of possible time-off types in the Freshteam system, an id is auto-generated for each time-off type. For example, if the organization configures Sick leave and Casual leave as the possible time-off types, the corresponding auto-generated ids can be 1 and 2. When a time-off request is raised, if Sick leave is chosen as the time-off type, leave_type_id is 1.
status_comments string Reason for declining or cancelling the time-off request.
For onTimeOffCreate, this value is an empty string.
approved_by_id integer Identifier of the employee who approves the time-off request. This is a valid employee.id value.
For onTimeOffCreate, this value is null.
applied_by_id integer Identifier of the employee who raises the time-off request.
cancelled_by_id integer Identifier of the employee who cancels the time-off request. Same as applied_by_id, if the time_off.status is cancelled.
For onTimeOffCreate, this value is null.
rejected_by_id integer Identifier of the employee who declines the time-off request.
For onTimeOffCreate, this value is null.
comments string Reason quoted by the employee for the time-off request.
rejected_at string Timestamp of when the reporting manager or HR partner declines the time-off request.
For onTimeOffCreate, this value is null.
cancelled_at string Timestamp of when the employee cancels the time-off request.
For onTimeOffCreate, this value is null.
cancelled_due_to_exit boolean Specifies whether the time-off request is cancelled because the employee has left the organization.
Possible values: true, false For onTimeOffCreate, this value is false.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
attachment attachment object Details of the document attached to the time-off request, if the time-off type is configured to accept an attachment.
leave_type timeoff type object Details of the time-off type under which the time-off request is raised.
applied_by employee model object Details of the employee who raises the time-off request.
user employee model object Details of the employee for whom the time-off request is raised. This attribute value is different from applied_by, only if an employee raises a time-off request for another employee.

Attributes of the attachment object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the attachment object, auto-generated when the attached document is stored.
content_file_name string Name of the attached document specified in the <base name>.<file type extension> format.
content_file_size string Size of the attached document specified in kilobytes.
description string Note that the time-off applicant specifies when uploading the attachment.
url string Link to the location from where the document can be retrieved.

Attributes of the time off type object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the timeoff type object, auto-generated when a vacation type is configured.
deleted boolean Specifies whether the time-off type is still a valid vacation type in the Freshteam system.
Possible values: true, false
name string Title of the time-off type.
description string Notes about the time-off type.
applicable_for string Specifies the eligibility for the time-off type based on gender.
Possible values: male, female, all
default boolean Specifies whether the time-off type is available by default to all employees.
Possible values: true, false
auto_approve boolean Specifies whether the time-off requests under the time-off type are auto-approved or sent to HR partners and reporting managers for further approval.
Possible values: true, false
auto_approve_after integer Number of days after which a time-off request that is pending approval is auto-approved.
auto_approve_limit integer Number of time-off request days beyond which a time-off request is sent for approval. For example if auto_approve_limit is 4, all requests for more than 4 days of time-off are sent for approval.
marital_status string Specifies the eligibility for the time-off type based on marital status.
Possible values: all, single, married

onTimeOffUpdate

When a time-off request is approved, declined, or cancelled (deleted) in the Freshteam system, the onTimeOffUpdate event is triggered.

Register the onTimeOffUpdate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onTimeOffUpdate": { "handler": "onTimeOffUpdateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onTimeOffUpdateCallback: function(payload) { console.log("Arguments from the onTimeOffUpdate event: " + JSON.stringify(payload)); } }
Sample Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onTimeOffUpdate", "region": "US", "data": { "timeoff": { "id": 10, "created_at": "2020-08-17 07:51:52 UTC", "updated_at": "2020-08-17 07:51:52 UTC", "user_id": 1, "start_date": "2020-08-27", "end_date": "2020-08-27", "status": "cancelled", "leave_units": 1, "optional_leave_units": null, "leave_type_id": 2, "status_comments": "", "approved_by_id": 2, "applied_by_id": 1, "cancelled_by_id": 1, "rejected_by_id": null, "comments": "Personal work", "rejected_at": null, "cancelled_at": "2020-08-19 05:14:46 UTC", "cancelled_due_to_exit": false }, "associations": { "attachment": { "id": 4, "content_file_name": "sample.docx", "content_file_size": 7448, "description": "timeoff", "url": "files.freshteam.com/docs/sample.docx" }, "leave_type": { "id": 2, "deleted": false, "name": "Earned", "description": "Earned Leave", "applicable_for": "all", "default": true, "auto_approve": false, "auto_approve_after": null, "auto_approve_limit": null, "marital_status": "all" }, "cancelled_by": { "id": 1, "first_name": "John", "last_name": "keith", "official_email": "john@freshteam.com" }, "applied_by": { "id": 1, "first_name": "John", "last_name": "keith", "official_email": "john@freshteam.com" }, "user": { "id": 1, "first_name": "John", "last_name": "keith", "official_email": "john@freshteam.com" } }, "actor": { "id": 9, "name": "Tyron Dr. Dena", "email": "124498fannie.jones@example.org" }, "changes": { "model_changes": { "cancelled_by_id": [ null, 1 ], "status": [ "approved", "cancelled" ], "cancelled_at": [ null, "2020-08-19 05:14:46 UTC" ] } } } }
EXPAND ↓

Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
timeoff timeoff object Information pertaining to the time-off request that is updated in the Freshteam system.
associations associations object All associated objects of the timeoff object, that provide additional information pertaining to the time-off request. This includes the documents attached to the request, information on the time-off type and applicant, information on the employee who approved, declined, or cancelled the time-off request, and so on.
The associations object contains one of the following objects based on the action that triggered onTimeOffUpdate:
  • cancelled_by: Details of the employee who cancels the time-off request.
  • approved_by: Details of the employee who approves the time-off request.
  • rejected_by: Details of the employee who declines the time-off request.
actor actor object Information pertaining to the user who updated or deleted the job posting.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.
changes object Changes that triggered the onTimeOffUpdate event, specified as a JSON object of the following format:
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "model_changes": { //For non-array attributes "<timeoff.attribute that changed>": ["Old value", "New value"], //For array attributes "<timeoff.attribute that changed>": { "added": [<array of newly added timeoff.attribute objects>], "changed": [["Old value1", "New value1"], ["Old value2", "New value2"]] } } }
EXPAND ↓
Note: For array attributes, any value that is deleted is specified in model_changes.changed with the deleted attribute set to true.
onApplicantCreate

When a new applicant is created or an existing candidate from the talent pool is moved as an applicant for a job posting in the Freshteam system, the onApplicantCreate event is triggered.

Register the onApplicantCreate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "onApplicantCreate": { "handler": "onApplicantCreateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { onApplicantCreateCallback: function(payload) { console.log("Arguments from the onApplicantCreate event: " + JSON.stringify(payload)); } }
Sample payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onApplicantCreate", "region": "US", "data": { "applicant": { "id": 16, "created_at": "2021-03-29T05:43:15.000Z", "updated_at": "2021-03-29T05:43:15.000Z", "deleted": false, "status": "open", "job_id": 3, "job_title": "QA Lead", "requisition_id": 5, "stage": "candidature", "sub_stage_id": 21, "on_hold_till": null, "on_hold_at": null, "rejected_at": null, "archived_at": null, "moved_at": null, "custom_fields": {} }, "associations": { "sub_stage": { "id": 21, "deleted": false, "name": "Open", "position": 1, "default": true, "stage": "candidature" }, "candidate": { "id": 10, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_gender": null, "first_name": "Jane", "middle_name": "", "last_name": "Sloan", "email": "janesloan@test.com", "source_id": 1, "source_category_id": 3, "spam": false, "description": null, "cool_off_date": null, "referred_by_id": null, "owner_id": 1, "tags": [], "skills": [], "location": { "city": null, "state": null, "street": null, "country_code": null, "zip_code": null }, "date_of_birth": null, "skype_id": null, "mobile": null, "phone": null, "profile_links": [ { "name": "web", "url": "" } ], "gender": null, "total_experience_in_months": null, "qualifications": [], "positions": [], "resumes": [], "cover_letters": [], "portfolios": [], "referrals": [] }, "followers": [ { "id": 16, "user_id": 5, "name": "Langdon Brennan", "email": "lbrennan@freshteam.com" } ] }, "actor": { "id": 1, "name": "John Smith", "email": "johnsmith@freshteam.com" } } }
EXPAND ↓
Attributes of the data object
Attribute Date Type Description
applicant applicant object Details of the candidate who is added as an applicant for a specific job posting. Addition of the applicant triggers the onApplicantCreate event.
associations associations object All associated objects of the applicant object, that specify additional information pertaining to the applicant. This includes information such as the qualification details, professional experience details, social profile information, and so on.
actor actor object Information pertaining to the user who added the applicant to the specific job posting.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): email address of the user. This is a valid employee.email value of an employee record that already exists.

Attributes of the applicant object
Attribute Date Type Description
id integer Details of the candidate who is added as an applicant for a specific job posting. Addition of the applicant triggers the onApplicantCreate event. Identifier of the applicant object, auto-generated when an applicant is created in the Freshteam system.
created_at string Timestamp of when an applicant is created in the freshteam system, specified in the UTC format.
updated_at string Timestamp of when the applicant details are last updated, specified in the UTC format.
For onApplicantCreate, this value is the same as the created_at value.
deleted boolean Specifies whether the applicant details still exist in the Freshteam system.
For onApplicantCreate and onApplicantUpdate triggered by record updation, this value is false.
For onApplicantUpdate triggered by record deletion, this value is true.
status string Status of the application.
Possible values:
open: The application is under processing and is considered for the job posting for which the application is received.
on_hold: The application is on-hold for a specified time period.
rejected: The application is deleted from the candidate pool corresponding to the job opening.
archived: The application is archived in the talent pool.
moved: The application is moved to another suitable job opening in the Freshteam system.
dropped: The application is blocked and all future applications from the applicant will be rejected.
job_id string Identifier of the job posting object that corresponds to the job opening for which the applicant is added to the candidate pool.
job_title string Descriptive identifier of the job posting for which the applicant is added to the candidate pool.
requisition_id string Identifier of the job requisition object that specifies the details of job requisitions associated with the job opening.
stage string Hiring stage of the applicant.
sub_stage_id string Identifier of the subdivision of the hiring stage of the applicant, auto-generated when a customized hiring stage is configured in the Freshteam system.
on_hold_till string Date and time till when the application is marked to be on-hold,specified in the UTC format.
on_hold_at string Timestamp of when the application is moved to an on-hold status, specified in the UTC format.
rejected_at string Timestamp of when the application is moved to a rejected status, specified in the UTC format.
archived_at string Timestamp of when the application is moved to an archived status, specified in the UTC format.
moved_at string Timestamp of when the application is moved from its previous state to the current state, specified in the UTC format.
custom_fields string Additional information about the applicant, specified through preconfigured custom fields. The custom_fields attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.

Attributes of the associations object
Attribute Date Type Description
sub_stage sub_stage object Details of the subdivision of the hiring stage of the applicant.
Attributes of the sub_stage object:
  • id (string): Identifier of the substage of the hiring stage, auto-generated when a customized hiring stage is configured in the Freshteam system.
  • deleted (boolean): Specifies whether the sub-stage is deleted from the Freshteam system.
    Possible values: true, false
  • name (string): Name of the sub-stage.
  • position (number): Place of the substage in the list of stages.
  • default (boolean): Specifies whether the substage is configured by default or customized. Possible values: true, false
  • stage (string): Name of the stage to which the substage associates with.
candidate candidate object Additional information about the applicant.
followers array of followers object Details of the users following the applicant.
Attributes of followers object:
id (string): Identifier of the followers object, auto-generated when a user is added as a follower of the applicant.
user_id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): Email address of the user. This is a valid employee.email value of an employee record that already exists.
onApplicantUpdate

When an applicant information is updated or edited in the Freshteam system, the OnApplicantUpdate event is triggered.

Register the OnApplicantUpdate event by using the following sample manifest.json content.

Copied Copy
1
2
3
4
5
"events": { "OnApplicantUpdate": { "handler": "OnApplicantUpdateCallback" } }

Define the corresponding callback by using the following sample server.js content:

Copied Copy
1
2
3
4
5
exports = { OnApplicantUpdateCallback: function(payload) { console.log("Arguments from the OnApplicantUpdate event: " + JSON.stringify(payload)); } }
Sample payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
{ "timestamp": 1496400354326, "account_id": "15", "domain": "sample.freshteam.com", "event": "onApplicantUpdate", "region": "US", "data": { "applicant": { "id": 17, "created_at": "2021-03-29T08:27:43.000Z", "updated_at": "2021-03-29T08:36:00.000Z", "deleted": false, "status": "open", "job_id": 3, "job_title": "QA Lead", "requisition_id": 5, "stage": "on_site", "sub_stage_id": 24, "on_hold_till": null, "on_hold_at": null, "rejected_at": null, "archived_at": null, "moved_at": null, "custom_fields": {} }, "associations": { "sub_stage": { "id": 24, "deleted": false, "name": "Technical round", "position": 1, "default": false, "stage": "on_site" }, "candidate": { "id": 3, "eeo_veteran": null, "eeo_ethnicity": null, "eeo_disabled": null, "eeo_gender": null, "first_name": "Gwen", "middle_name": null, "last_name": "Stacy", "email": "gwen@example.com", "source_id": 1, "source_category_id": 1, "spam": false, "description": "Results-oriented Sales Account ", "cool_off_date": null, "referred_by_id": null, "owner_id": 11, "tags": [ "sas" ], "skills": [], "location": { "city": null, "state": "New Jersey", "street": null, "country_code": null, "zip_code": null }, "date_of_birth": null, "skype_id": null, "mobile": "+19876543210", "phone": null, "profile_links": [ { "name": "web", "url": "" } ], "gender": "female", "total_experience_in_months": null, "qualifications": [], "positions": [], "resumes": [], "cover_letters": [], "portfolios": [], "referrals": [] }, "followers": [ { "id": 16, "user_id": 5, "name": "Langdon Brennan", "email": "lbrennan@freshteam.com" } ] }, "actor": { "id": 1, "name": "John Smith", "email": "johnsmith@freshteam.com" }, "changes": { "model_changes": { "status": ["archived","open"], "sub_stage_id": [21,24], "followers": { "added": [ { "id": 16, "user_id": 5, "name": "Langdon Brennan", "email": "lbrennan@freshteam.com" } ] } } } } }
EXPAND ↓
Attributes of the data object
Attribute Date Type Description
applicant applicant object Information pertaining to the applicant that is updated or deleted from the Freshteam system. The updation or deletion of applicant details triggers the OnApplicantUpdate event.
When the applicant detail is deleted, the applicant.deleted value is true.
associations associations object All associated objects of the applicant object, that specify additional information pertaining to the applicant. This includes information such as the qualification details, professional experience details, social profile information, and so on.
actor actor object Information pertaining to the user who updated the applicant to the specific job posting.
Attributes of the actor object:
id (string): Identifier of the user. This is a valid employee.id value of an employee record that already exists.
name (string): Name of the user.
email (string): Email address of the user. This is a valid employee.email value of an employee record that already exists.
changes object Changes that triggered the on OnApplicantUpdate event, specified as a JSON object of the following format: Copied Copy
1
2
3
4
5
6
7
8
9
10
11
{ "model_changes": { //For non-array attributes "<applicant.attribute that changed>": ["Old value", "New value"], //For array attributes "<applicant.attribute that changed>": { "added": [<array of newly added applicant.attribute objects>], "changed": [["Old value1", "New value1"], ["Old value2", "New value2"]] } } }
Note: For array attributes, any value that is deleted is specified in model_changes.changed with the deleted attribute set to true.
Test

For information on how to simulate a product event and test your app, see Test the app.