Overview

Freshteam is a cloud based HR software that enables businesses to set up a branded HR portal that encompassess employee, recruitment, on-boarding, time-off, off-boarding, and organization details management.

You can use the Freshteam APIs to synchronize the employee directory maintained in Freshteam with any HR tool. Through APIs, you can access employee and organization information and respond to changes in the information when new employees are hired, appraisals are performed, promotions are meted out, policies are changed, employees are off-boarded, and so on.

Status and error messages

Freshteam uses the following standard HTTP status codes to indicate the success or failure of an API request.

  • 200 Success Request
  • 201 Created
  • 400 Bad Request
  • 401 Unauthenticated Request
  • 403 Forbidden
  • 404 Resource Not Found
  • 405 Method Not Allowed
  • 406 Not Acceptable
  • 415 Unsupported Media Type
  • 429 Too Many Requests
  • 500 Internal Server Request

A successful create request returns 201 Created along with the created object. A successful update request returns 200 OK along with the updated object. An unsuccessful API request returns a relevant HTTP status code along with an error response.

The error response

Example

1
2
3
4
5
6
7
8
{
	"errors": [{
		"code": "invalid_value",
		"message": "Value not present in system",
		"field": "leave_type_id"
	}]
}

Attributes

errors (array of error object): All errors that cause the request to fail, specified as an array. Each array entry is an error object with the corresponding attributes.

Attributes of the error object
Attribute Name Data Type Description
code string

Descriptive error code that corresponds to the standard HTTP code.

Possible values:

  • invalid_credentials: (401) Incorrect or missing authentication or authorization credentials.
  • forbidden: (403) Inadequate role privilege to make the API request.
  • not_found: (404) Invalid request URL to access a resource.
  • method_not_allowed: (405) Invalid method in the API request. For example, a PUT /api/employees request returns this error.
  • invalid_accept_header: (406) Inavlid value for the Accept header parameter. Valid parameter values are application/json and */*.
  • invalid_content_type: (415) Invalid value for the Content-Type header parameter. Valid parameter value is application/json.
  • invalid_value: (400) Incorrect value or invalid format for an attribute value.
  • missing_value: (400) Missing value for a mandatory attribute.
  • duplicate_value: (400) Input attribute value is not unique for an attribute whose value must be unique.
  • datatype_mismatch: (400) Invalid data type for an attribute value.
  • internal_server_error: (500) Unexpected error caused from the Freshteam side.
message string Freshteam specific message that states the cause of the error.
field(displayed only for 400 Bad Request errors) string Identifies the attribute that causes the error.

Date and time literals

All system generated timestamps in the date-time format follow the Coordinated Universal Time (UTC) standard.
All attributes that accept or return data in the date format, follow the YYYY-MM-DD format.

Header parameters

Common request header parameters that are used in requests to Freshteam APIs are as follows:

  • Accept
  • Authorization
  • Content-Type

Accept

Specifies the accepted format of response. The parameter is used in the API request that is expected to return a response body.

Header parameter format

Accept: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the response must be a JSON object.
A parameter value of */* specifies that response data of any type is acceptable.

Authorization

Specifies the credentials required to authenticate and authorize an API request.

Header parameter format

Authorization: Bearer <access-token>

<access-token> is the value returned by a request call to the authentication server.

Content-Type

Specifies the format in which data is sent in the request body.

Header parameter format

Content-Type: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the request body is a JSON object.

Authentication and authorization

Freshteam uses Oauth 2.0 for authentication and authorization and the process involves the following steps:

  1. From the Freshteam UI, make a call to the Freshteam authentication server, to obtain an access token.
  2. Use the access token in further API requests, to make valid API calls.

In the Oauth 2.0 authentication scheme, the access token identifies a requester and the requester’s permissions.

Request call to obtain the access token
  1. Navigate to the Freshteam domain and click the profile icon on the right. A menu is displayed.
  2. Select API Settings. The API Settings window is displayed. The access token (obtained by a call to the authentication server) is displayed under Your API Key. You can copy and use the key in the authorization header parameter, to make valid API requests.

Rate limits

The permissible number of API calls in a minute is based on the Freshteam plan opted for an organization. The rate limit for each plan is based on the number of subscribed employees in the organization. The rate limit is applicable to an account, irrespective of the IP address from which calls originate.

Freshteam Plan Rate Limit (per minute)
Free Nil
Trial 10
Growth and Pro MAX(50, number of subscribed employees)
Enterprise MAX(100, 2 * number of subscribed employees)

The following parameters in an API response header help to track the rate limits:

Parameter Name Description
x-ratelimit-total Permissible number of API calls in a minute.
x-ratelimit-remaining Number of API calls remaining.
x-ratelimit-used-currentrequest Number of API calls consumed by the API request that obtained the response.

Employees

Employees are members of the business or organization that uses Freshteam. An organization collects, stores, and updates all employee information through the records or fields in an employee information form. Freshteam offers a comprehensive list of default fields. An organization can also add custom fields. All field related information are grouped as employee fields.

Endpoints

GET /employees
POST /employees
GET /employees/{id}
PUT /employees/{id}
GET /employee_fields
POST /employee_fields

The employee object

Example 
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
{
  "id": 3000053373,
  "created_at": "2019-09-15T09:17:43.000Z",
  "updated_at": "2019-10-17T13:56:13.000Z",
  "deleted": false,
  "work_numbers": [
    {
      "name": "Work",
      "number": "9716638376"
    }
  ],
  "nick_name": null,
  "date_of_birth": null,
  "gender": "male",
  "phone_numbers": [],
  "designation": null,
  "joining_date": "2019-09-25",
  "termination_date": null,
  "first_name": "Aditya",
  "middle_name": null,
  "last_name": "Sharma",
  "employee_id": "E001",
  "employee_type": "full time",
  "draft": false,
  "terminated": false,
  "status": "active",
  "official_email": "aditya.sharma+2519@freshworks.com",
  "personal_email": null,
  "branch_id": 3,
  "team_id": 3000043460,
  "department_id": 1,
  "sub_department_id": 1,
  "business_unit_id": 4,
  "reporting_to_id": 3,
  "hr_incharge_id": 3,
  "shift_id": 1,
  "address": {
    "street": "1312 Pape Avenue",
    "state": "Ontario",
    "city": "Toronto",
    "country_code": "CA",
    "zip_code": ""
  },
  "communication_address": {
    "communication_street": "1312 Pape Avenue",
    "communication_state": "Ontario",
    "communication_city": "Toronto",
    "communication_country_code": "CA",
    "communication_zip_code": "",
    "same_as_residential": false
  },
  "custom_field_values":{
    "hobbies_cf_str01":null,
    "citizenship_cf_str02":{"id":0,"value":null}
  },
  "team": {
    "id": 3000043460,
    "created_at": "2019-09-15T09:17:43.000Z",
    "updated_at": "2019-09-15T09:17:43.000Z",
    "deleted": false,
    "name": "Business"
  }
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id number Identifier of the employee object, auto-generated when an employee’s information is saved. A successful create employee request, returns this attribute as part of the response object. Further API requests can use the returned value to identify an employee and update the employee information.
created_at string Timestamp of when the employee information is created, specified in the date-time format. The timestamp is returned as part of the response employee object, on successful processing of an employee create request.
updated_at string Timestamp of when the employee information is last updated, specified in the date-time format. The timestamp is returned as part of the response employee object, on successful processing of an employee create request. If an employee’s details are not updated, the updated_at and created_at values are same.
deleted boolean If true, specifies that the employee is no longer part of the organization and the employee record is deleted from the Freshteam system.
Possible values: true, false
work_numbers array of work number object Official phone numbers of the employee, specified as an array of work number object.
workstation_number string Work desk number of the employee.
nick_name string Alternate display name for the employee, in the Freshteam system.
date_of_birth string Birth date of the employee, specified in the date format.
gender string Gender of the employee.
Possible values: male, female.
address address object Residential address of the employee.
communication_address communication address object Address to which all official communication is sent.

Attributes of the CommunicationAddress object:
communication_street (string)
communication_city (string)
communication_state (string)
communication_country (string)
communication_zip_code (string)
same_as_residential (boolean): The attribute is part of the response object only if the attribute value is false.
designation string Job title of the employee.
phone_numbers array of phone number object Contact numbers of the employee, specified as an array of phone number objects.
joining_date string Date when the employee joins the organization, specified in the date format.
termination_date string Date when the employee leaves the organization, specified in the date format.
first_name Mandatory string Business name of the employee.
last_name Mandatory string Last name of the employee.
middle_name string Middle name 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.
official_email Mandatory string Official email address of the employee.
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.
draft boolean If true, specifies that the employee is a current employee of the organization and the employee’s record is being drafted.
Posbsible values: true, false
terminated boolean If true, specifies that the employee is no longer part of the organization and the employee record is archived.
Possible values: true, false
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.
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.
business_unit_id string Identifier of the business function to which the employee belongs. This is the business unit.id value that is auto-generated when the business unit’s information is configured in Freshteam.
sub_department_id string Identifier of the subcategory of the job role to which the employee belongs. This is the sub_department.id value that is auto-generated when the sub-department’s information is configured in Freshteam.
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.
shift_id string Identifier of the shift to which the employee belongs. This is the field option.id value that is auto-generated when the shift is configured in Freshteam.
time_off array of employee time off object Leave of absence information of the employee, specified as an array of employee time off objects.
The following attributes contain additional employee information. For an employee, if the additional information is available in Freshteam, when retrieving the employee’s information, the following attributes are returned as part of the response object.
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.
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.
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
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.
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.
termination_date string Date when the employee leaves the organization, specified in the YYYY-MM-DD format.
termination_reason string Reason stating why the employee leaves the organization, specified by the person who updates the employee record.
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.
notice_end_date string Ending date of the notice period, updated after the employee’s termination is approved.
rehire_eligibility boolean Specifies whether the employee, whose services have ended, is eligible to be hired in the future.
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_field_values object The organization that uses Freshteam can configure custom fields to obtain additional employee information. 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.
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.
cost_center_id string Identifier of the cost center to which the employee belongs. This is the field option.id value that is auto-generated when the shift is configured in Freshteam.
user_title_id string Identifier of the title associated with the employee. This is the field option.id value that is auto-generated when the title is configured in Freshteam.
user_suffix_name_id string Identifier of the name suffix associated with the employee. This is the field option.id value that is auto-generated when the name suffix is configured in Freshteam.
user_honorary_suffix_id string Identifier of the honorary title bestowed to the employee. This is the field option.id value that is auto-generated when the honorary suffix is configured in Freshteam.
user_professional_suffix_id string Identifier of the professional suffix associated with the employee. This is the field option.id value that is auto-generated when the professional suffix is configured in Freshteam.
user_academic_suffix_id string Identifier of the academic qualification, which can be specified as a suffix, associated with the employee. This is the field option.id value that is auto-generated when the academic suffix is configured in Freshteam.
citizenship_status_id string Identifier of the employee’s citizenship status. This is the field option.id value that is auto-generated when the citizenship status is configured in Freshteam.
retirement_status_id string Identifier of the retirement status associated with the employee. This is the field option.id value that is auto-generated when the retirement status is configured in Freshteam.
termination_category_id string Identifier of the termination category under which the employee ceases to work for the organization. This is the (field option).id value that is auto-generated when the termination category is configured in Freshteam.
The following attributes are embedded attributes. When retrieving an employee’s information, you can use the include query parameter to retrieve these attributes as part of the response object.
awards array of award object All awards associated with the employee, specified as an array of award objects.
honors array of honor object All honorary titles associated with the employee, specified as an array of honour objects.
certificates array of certificate object All certificates awarded to the employee, specified as an array of certificate objects.
licenses array of license object Information from all license documents, specified as an array of license object.
background_verification_details array of bgv detail object Background verification details, specified as an array of bgv details object.
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 object All details in the government documents uploaded by the employee, specified as an array of government documents object.
dependents array of dependent object All details of an employee’s dependents, specified as an array of dependent objects.
bank_accounts array of bank account object All details of the employee’s bank accounts, specified as an array of bank account objects.
prev_employments array of previous employment object All details of the employee’s previous employment positions, specified as an array of previous employment objects.
qualifications array of qualification object All details of the employee’s education, specified as an array of qualification objects.
compensation_details array of compensation detail object All details of the employee’s compensation, specified as an array of compensation detail objects.
bonuses array of bonus object All details of the employee’s various bonuses, specified as an array of bonus objects.
stocks array of stock object All details of the employee’s stock grant options, specified as an array of stock 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
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.
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.
business_unit business unit object Details of the business function to which the employee belongs.
sub_department sub-department object Details of the sub-department 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.
reporting_to employee model object Details of the employee's reporting manager.
hr_incharge employee model object Details of the employee's HR manager.
shift field option object Shift to which the employee belongs. For example, Day shift, EMEA shift, and so on.
user_function field option object Specific function that the employee performs as part of a team. For example, GTM, design, and so on.
cost_center field option object Cost group to which the employee belongs.
user_title field option object Title associated with the employee. For example, Mr., Ms., and so on.
user_suffix_name field option object Name suffix associated with the employee. For example, Jr., Sr., and so on.
user_honorary_suffix field option object Honorary title bestowed to the employee. For example, OBE, MBE, and so on.
user_professional_suffix field option object Professional suffix associated with the employee. For example, CFA, CPA, and so on.
user_academic_suffix field option object Academic qualification, which can be specified as a suffix, associated with the employee. For example, M.S, Ph.D, and so on.
retirement_status field option object Retirement status associated with the employee. For example, Retired, Voluntary retirement process, and so on.
citizenship_status field option object Retirement status associated with the employee. For example, Retired, Voluntary retirement process, and so on.
termination_category field option object Termination category under which the employee ceases to work for the organization. For example, Resignation, End of Contract, Involuntary, and so on.

Attributes of the work number object

Attribute Name Data Type Description
name string Type of phone number.
Possible values (enum): Work, Office Ext., Mobile, Others
number string Official contact number of the employee.

Attributes of the address object

Attribute Name Data Type Description
street string Street name, PO Box number, apartment complex, building identifier, or any other similar component of the employee’s residential address.
Minimum length: 2 characters
Maximum length: 128 characters
city string City, district, town, or any other similar component of the employee’s residential address.
Minimum length: 2 characters
Maximum length: 128 characters
state string State, region, province, county, or any other sub component of the employee’s residential address.
Minimum length: 2 characters
Maximum length: 128 characters
country string Country name or code.
Minimum length: 2 characters
Maximum length: 128 characters
zip_code string ZIP or postal code.
Minimum length: 2 characters
Maximum length: 128 characters

Attributes of the phone number object

Attribute Name Data Type Description
name string Type of phone number.
Possible values (enum): Home, Main, Mobile, Others
number string Personal contact number of the employee.

Attributes of the employee model object

Attribute Name Data Type Description
id number Identifier of the employee object, auto-generated when an employee’s (HR manager or reporting manager) information is created in the Freshteam system. Must be valid employee.id value.
city string City, district, town, or any other similar component of the employee’s residential address.
Minimum length: 2 characters
Maximum length: 128 characters
first_name string Business name of the HR or reporting manager.
last_name string Last name of the HR or reporting manager.
email string Official email address of the HR or reporting manager.

Attributes of the award object

Attribute Name Data 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 honour object

Attribute Name Data 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 certificate object

Attribute Name Data 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 license object

Attribute Name Data 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 detail object

Attribute Name Data 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 (enum): 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 Name Data 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

Attributes of the dependent object

Attribute Name Data 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 bank account object

Attribute Name Data 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

Attributes of the previous employment object

Attribute Name Data 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 Name Data 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.

The compensation detail object

Example

{"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"}
}

Attributes

Attribute Name Data 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 Name Data 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

{ "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" }
}

Attributes

Attribute Name Data 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 (enum): 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 (enum): 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 employee timeoff object

Attribute Name Data Type Description
leave_type timeoff type model object Type of leave the employee is eligible to take.

Attributes of the timeoff type model object:
id (number): Identifier of the timeoff type object, auto-generated when a time-off type is configured in the system. Must be a valid time_off_type.id value.
value (string): Descriptive identifier of the time-off type. Must be a valid time_off_type.name value. For example, Sick, Earned, and so on.
leaves_availed number Number of leaves the employee has taken under a specific leave category.
leave_credits number Number of leaves the employee is eligible to take, under a specific leave category.

Attributes of the field option object

Attribute Name Data Type Description
id number Fields to collect specific types of employee information such as the shift or cost group to which the employee belongs, honorary or academic title associated with the employee, and so on, can be configured in Freshteam.
id is the identifier assigned to each possible value of such fields, auto-generated when the possible values are configured in Freshteam.
value string A possible value of the field. For example, if the organization configures Mr. and Ms. as the possible user 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, the user_title_id is 12. The associated embedded attribute is user_title. user_title.id is 12 and user_title.value is Mr..

The employee field object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"id":860161,
"created_at":"2019-09-15T09:17:45.000Z",
"updated_at":"2019-09-15T09:17:45.000Z",
"employee_form_id":3000008188,
"name":"basic_info",
"label":"General Information",
"field_type":"field_group",
"position":1,
"default":true,
"viewable_by":"all",
"editable_by":"self",
"tab":"personal",
"field_scopes":[]
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id number Identifier of the employee field object, auto-generated when a new field is configured for an employee information form.
created_at string Timestamp of when the field is created, specified in the date-time format.
updated_at string Timestamp of when the field details are last modified, specified in the date-time format.
deleted boolean Specifies whether the field is still a valid field in the employee information form.
Possible values: true, false.
employee_form_id integer Identifier of the employee form in which the employee fields are present.
name string Namespace identifier of the section where the employee field is present.
For example, basic_info, additional_info, and so on.
label string Display name of the employee field.
field_type string Type of the employee field. The different field types are predefined in the Freshteam system. The field_type for all sections in the employee form is field_group.
Possible values (enum): See, supported field_type values.
position integer Position of the employee field in the employee form. The numbering is from left to right and top to bottom.
required boolean Specifies whether the employee field is a mandatory field.
default boolean Specifies whether an employee field is a default field in the Freshteam system.
For all custom fields, this attribute value is false. Possible values: true, false
viewable_by string View permissions for the employee field. View permissions are set at the section level. Only fields of the field_group type have a corresponding viewable_by field.
Possible values (enum):
all: All users of the Freshteam account can view the employee field values.
self: Only the employee can view the values.
hr: Only the HR associated with the employee can view the values.
self_hr: The employee, the employee’s HR, and the employee’s reporting manager can view the values.
editable_by string Edit permissions for the employee field. Edit permissions are set at the section level. Only fields of the field_group type have a corresponding editable_by field.
Possible values (enum):
self: Only the employee can edit the values.
hr: Only the HR associated with the employee can edit the values.
tab string Name of the tab on the employee form, under which the employee field (section) is present. Only fields of the field_group type have a corresponding tab field.
section_label string Display name of the section to which the employee field belongs. Only fields whose field type is not field_group have a corresponding section_label field.
field_scopes array of field scope object Employee groups to which the employee field is applicable.

Attributes of the field scope object:
id (integer): Identifier of the field scopes object, auto-generated when the applicability information is configured for a section on the employee form.
scopable_type (string): Identifier of the employee group to which the section is applicable. For example, team, department, branch, level, and so on.
scopable_id (number): Identifier of the sub-group to which the section is applicable.

For example, if a section on the employee form is applicable to the Business (teams.id is 3000043460), Corporate Marketing (teams.id is 3000043467), and Customer Success (teams.id is 3000043462) teams, the corresponding field_scopes attribute is as follows:

"field_scopes":[ {"id":32,"scopable_type":"teams","scopable_id":3000043460}, {"id":33,"scopable_type":"teams","scopable_id":3000043467}, {"id":34,"scopable_type":"teams","scopable_id":3000043462} ]
Supported field_type values

When creating or updating employee information, appropriate values are specified for the custom fields (create_employee.custom_field). A valid custom field value must be of the data type corresponding to the field type (employee_field.field_type). The supported field_type values (and corresponding data types) are as follows:

  • text (string)
  • dropdown (string)
  • email (string)
  • phone_number (string)
  • checkbox (boolean - 0, 1)
  • paragraph (string)
  • date_time (string)
  • number (number)
  • url_set (string)
  • url (string)
  • attachment (number)
  • radio (string)
  • label (string)
  • field_group (string)
  • emergency_contact (object)
  • phone_number_set (object)
  • social_profile (array)
  • address (object)
  • previous_employment (object)
  • education (object)
  • avatar (string)
  • bank_details (object)
  • compensation (object)
  • standard_email (string)
  • standard_dropdown (string)
  • standard_multi_dropdown (array)
  • file_input (string)
  • visa (object)
  • bg_verification (object)
  • government_id (object)
  • licenses (object)
  • certifications (object)
  • awards (object)
  • honours (object)
  • comp_bonuses (object)
  • stock_grants (object)
  • dependents (object)
  • time (string)
  • personal_contact_set (object)

List all employees

Retrieves a list of all employees whose details are configured in the Freshteam system.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/employees
Query parameters

You can use a combination of the following query parameters to limit or filter the bulk response data. Ensure that the query parameter values are URL encoded.

Parameter Name Description Example
status Limits the response to employee objects whose status value matches the parameter value.
Valid values: active, inactive

GET /api/employees?status=active
first_name Limits the response to employee objects whose first_name value matches the parameter value.

GET /api/employees?first_name=Dreda
last_name Limits the response to employee objects whose last_name value matches the parameter value.

GET /api/employees?last_name=Dreda
personal_email Limits the response to employee objects whose personal_email value matches the parameter value.

GET /api/employees?personal_email=dreda%40gmail.com
official_email Limits the response to employee objects whose official_email value matches the parameter value.

GET /api/employees?official_email=lbrenan%40freshteam.com
employee_type Limits the response to employee objects whose employee_type value matches the parameter value.

GET /api/employees?employee_type=contract
department Limits the response to employee objects whose department_id value matches the parameter value.

GET /api/employees?department=3000016570
business_unit Limits the response to employee objects whose business_unit_id value matches the parameter value.

GET /api/employees?business_unit=3000000015
location Limits the response to employee objects whose branch_id value matches the parameter value.

GET /api/employees?location=3000011495
reporting_manager Limits the response to employee objects whose reporting_to_id value matches the parameter value.

GET /api/employees?reporting_manager=3000053373
updated_since

Should be a date-time value in the UTC standard.		 Limits the response to employee objects whose updated_at value is a time after the parameter value.

GET /api/employees?updated_since=2019-12-06T06:00:33.000Z
sort Specifies the field based on which the response data is sorted.
Valid values: first_name, last_name, employee_id

GET /api/employees?sort=first_name
sort_type If the sort value is specified, sort_type specifies whether the list must be sorted in ascending or descending order. If sort_type is specified with no sort value, the list is sorted based on the first_name attribute.
Valid values: asc, desc

GET /api/employees?sort=first_name&sort_type=asc
Note: If all three of the following parameters are specified as true, the query returns an empty array.
draft

Note: If status is specified as inactive and draft as true, the query returns an empty array. 		Limits the response to employee objects whose draft value matches the parameter value.
Valid values: true, false

GET /api/employees?draft=true
terminated

Note: If status is specified as active and terminated as true, the query returns an empty array. 		Limits the response to employee objects whose terminated value matches the parameter value.
Valid values: true, false

GET /api/employees?terminated=true
deleted

Note: If status is specified as inactive and deleted as false, the query returns an empty array. 		Limits the response to employee objects whose deleted value matches the parameter value.
Valid values: true, false

GET /api/employees?deleted=true
Example to retrieve all the details of the employees in branches 3000011495 and 3000011496 and sort the information in ascending order of first names:

GET /api/employees?location=3000011495,3000011496&sort=first_name&sort_type=asc
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/employees"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all employees’ details, as an array. Each array entry is an employee object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. 

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
[{
"id":3000000046,
"created_at":"2017-07-22T06:01:09.000Z",
"updated_at":"2020-06-24T09:58:11.000Z",
"deleted":false,
"work_numbers":[{"name":"Mobile","number":"0403965567"}],
"nick_name":"",
"date_of_birth":null,
"gender":null,
"address":{"street":"","state":"","city":"","country_code":null,"zip_code":""},
"phone_numbers":[],
"communication_address":{"same_as_residential":false,"communication_street":"","communication_state":"","communication_city":"","communication_country_code":"","communication_zip_code":""},
"designation":"Senior UI/UX Designer",
"joining_date":"2018-02-14",
"branch_id":3000000742,
"team_id":3000000012,
"business_unit_id":3000000015,
"sub_department_id":null,
"department_id":null,
"reporting_to_id":null,
"hr_incharge_id":null,
"shift_id":null,
"termination_date":"2019-05-15",
"first_name":"Shal",
"middle_name":"",
"last_name":"Pill",
"employee_id":"",
"status":"active",
"official_email":"Shal.pill@freshworks.com",
"personal_email":"",
"employee_type":"full_time"
},
{
"id":3000084693,
"created_at":"2020-03-17T06:39:57.000Z",
"updated_at":"2020-05-19T05:33:05.000Z",
"deleted":false,
"work_numbers":[{"name":"Work","number":"+919176314553"},
{"name":"Mobile","number":"+919176314553"}],
"nick_name":null,
"date_of_birth":null,
"gender":null,
"address":{"street":"","state":"","city":""},
"phone_numbers":[],
"communication_address":{"same_as_residential":false,"communication_street":"","communication_state":"","communication_city":""},
"designation":null,
"joining_date":null,
"branch_id":3000002001,
"team_id":null,
"business_unit_id":null,
"sub_department_id":null,
"department_id":null,
"reporting_to_id":null,
"hr_incharge_id":null,
"shift_id":null,
"termination_date":null,
"first_name":"Aishwarya",
"middle_name":null,
"last_name":"Ray",
"employee_id":"534",
"status":"active",
"official_email":"aishwarya.ray@freshworks.com",
"personal_email":null,
"employee_type":"full_time"
}]
EXPAND ↓

Create an employee

Creates an employee object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

post
/api/employees
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
curl -X POST "https://<account-name>.freshteam.com/api/employees" -H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" -H "Content-Type: application/json"
  -d '{
      "first_name": "John",
      "last_name": "Smith",
      "official_email": "john@freshteam.com",
      "role_ids": [ 3000060416 ]
}'
EXPAND ↓
The request body parameter
Example 
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
{
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Smith",
      "official_email": "john@freshteam.com",
      "employee_type": "contract",
      "role_ids": [ 3000060416 ],
      "employee_id": "E001",
      "personal_email": "john@new.com",
      "work_numbers": [
        {
          "name": "Work",
          "number": "9716638376"
        }
      ],
      "phone_numbers": [],
      "date_of_birth": "1993-08-03",
      "designation": "Developer",
      "joining_date": "2018-06-25",
      "branch_id": 3000011496,
      "hr_incharge_id": 3000053377,
      "reporting_to_id": 3000053373,
      "business_unit_id": 3000016570,
      "sub_department_id": null,
      "shift_id": 430461,
      "department_id": 3000129089,
      "team_id": 3000047560,
      "level_id": 3000056483,
      "blood_group": "",
      "gender": "male",
      "address": { "street": "101 SP Apts", "city": "Bangalore", "state": "Karnataka", "country": "India", "zip_code": "7001" },
      "communication_address": { "communication_street": "2950 Firstwood street", "communication_city": "San Mateo", "state": "CA", "country": "US", "zip_code": "94403", "same_as_residential": true },
      "custom_fields": { "hobbies_cf_str01": null},
      "draft": false,
      "cost_center_id": null,
      "id_card_deails": null,
      "send_invite_email": false
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
first_name Mandatory string Business name of the employee.
middle_name string Middle name of the employee.
last_name Mandatory string Last name of the employee.
official_email Mandatory string Official email address of the employee.
role_ids Mandatory array of integer Identifiers of all roles associated with the employee, specified as an array of valid role.id values.
employee_id integer Employee ID provided by the organization that uses Freshteam.
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.
work_numbers array of work number object Official phone numbers of the employee, specified as an array of work number object.
phone_numbers array of phone number object Contact numbers of the employee, specified as an array of phone number objects.
date_of_birth string Birth date of the employee specified in the date format.
designation string Job title of the employee.
Maximum permissible length: 128 characters
joining_date string Date when the employee joins the organization, specified in the date format.
branch_id integer Identifier of the branch to which the employee belongs. Must be a valid branch.id value.
hr_incharge_id integer Identifier of the person assigned as the hr incharge of the employee. Must be a valid employee.id value.
reporting_to_id integer Identifier of the person assigned as the reporting manager of the employee. Must be a valid employee.id value.
business_unit_id integer Identifier of the business function to which the employee belongs. Must be a valid business unit.id value.
sub_department_id integer Identifier of the subcategory of the job role to which the employee belongs. Must be a valid sub_department.id value.
shift_id integer Identifier of the shift to which the employee belongs. Must be a valid shift.id value.
department_id integer Identifier of the department to which the employee belongs. Must be a valid department.id value.
team_id integer Identifier of the primary group to which the employee belongs. Must be a valid team.id value.
level_id integer Identifier of the job band to which the employee belongs. Must be a valid level.id value.
blood_group string Blood group of the employee.
Possible values (enum): A−, B−, O−, B+, O+, A+, A1+, A1B-, AB+, AB-, A1B+, A2+, A2B-, A2B+, A1-
gender string Gender of the employee.
Possible values: male, female.
address address object Residential address of the employee.
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 (string)
communication_zip_code (string)
same_as_residential (boolean)
custom_fields array of object All custom field names and corresponding values, specified as a valid JSON object of key (custom field name)-value(custom field’s value) pairs. The custom field name must be a valid employee_field.name value. The data type of the custom field's value depends on the type of the custom field. For example, if the custom field is a text field, the custom field's value is a string. If the custom field is a checkbox, the value is 0 or 1.
For more information, see the Supported field_type values.
draft boolean Specifies whether the employee information created is retained in the draft mode or saved for further processing.
Possible values (enum): true, false
cost_center_id string Identifier of the cost center to which the employee belongs. This is the field option.id value that is auto-generated when the cost center is configured in Freshteam.
id_card_details string Number or code associated with the ID card allocated for the employee.
send_invite_email boolean Specifies whether an email is sent to the employee inviting the employee to the Freshteam system, when the employee information is configured.
Possible values (enum): true, false
Sample response

A successful request returns 201 Created along with the created employee object. The object contains the id, created_at, and updated_at attributes. In further API calls, the id that is returned can be used to update the corresponding employee information or retrieve information.

Retrieve employee information

Identifies an employee by the id passed in the request and returns the corresponding information as an employee object.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/employees/{id}
Path parameters
Parameter Name Data Type Description
idMandatory number The employee.id value that is auto-generated when an employee’s details are configured in the Freshteam system.
Query parameters

To restrict the response (payload) object size, certain attributes are not specified as part of the employee object by default. In the query string of the request URL, you can use the include query parameter, to retrieve the following employee object’s attributes.

  • awards
  • honors
  • certificates
  • licenses
  • background_verification_details
  • visas
  • government_documents
  • dependents
  • user_documents
  • bank_accounts
  • prev_employments
  • qualifications
  • compensation_details
  • bonuses
  • stocks
  • additional_teams
  • additional_managers
  • additional_hr_managers
  • languages
  • roles
  • team
  • branch
  • business_unit
  • sub_department
  • department
  • reporting_to
  • hr_incharge
  • level
  • shift
  • user_function
  • cost_center
  • user_title
  • user_suffix_name
  • user_honorary_suffix
  • user_professional_suffix
  • user_academic_suffix
  • retirement_status
  • citizenship_status
  • termination_category
Example to include compensation_details in the response object:

GET /api/employees/3000053373?include=compensation_details

Example to include compensation_details and time_off in the response object:

GET /api/employees/3000053373?include=compensation_details,time_off

Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/employees/3000053373"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved employee object.

Update employee information

Identifies an employee object by the id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

put
/api/employees/{id}
Path parameters
Parameter Name Data Type Description
idMandatory number The employee.id value that is auto-generated when an employee’s details are configured in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
curl -X POST "https://<account-name>.freshteam.com/api/employees" -H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" -H "Content-Type: application/json"
	-d '{
			"first_name": "John",
			"middle_name":"L"
			"last_name": "Smith",
			"official_email": "john@freshteam.com",
			"role_ids": [ 3000060416 ]
}'
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated employee object.

List all employee fields

Retrieves a list of all default and custom employee fields configured for an organization, in the Freshteam system.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/employee_fields
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/employee_fields"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all employee fields’ details, as an array. Each array entry is an employee field object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
{
"id":1361440,
"created_at":"2020-03-26T14:48:00.000Z",
"updated_at":"2020-03-26T14:48:00.000Z",
"employee_form_id":3000000001,
"name":"profile_info",
"label":"Profile Information",
"field_type":"field_group",
"position":1,
"default":true,
"viewable_by":"all",
"editable_by":"self",
"tab":"personal",
"field_scopes":[]
},
{
"id":39,
"created_at":"2018-11-24T12:06:32.000Z",
"updated_at":"2018-11-24T12:06:32.000Z",
"employee_form_id":3000000001,
"name":"employee_id",
"label":"Employee Id",
"field_type":"text",
"position":1,
"default":true,
"section_label":"Work Information",
"required":false
}
]
EXPAND ↓

Create a custom employee field

Creates a custom employee field, in an employee form, based on the request body parameter. The request body parameter (input payload) should be a valid JSON object of the specified format..

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

post
/api/employee_fields
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
curl -X POST "https://<account-name>.freshteam.com/api/employee_fields" -H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" -H "Content-Type: application/json"
-d '{"label": "Hobbies",
  "required": false,
  "section_name": "additional_info",
  "field_type": "text"
}'
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
{
  "label": "Hobbies",
  "required": false,
  "section_name": "additional_info",
  "field_type": "text"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
label Mandatory number Display name of the custom field.
required boolean Specifies whether the custom field is a mandatory employee field.
Possible values: true, false
section_name Mandatory string Namespace identifier of the section where the custom field is created. Must be a valid employee_field.name value.
field_type string Specifies the type of the custom field.
Possible values (enum): text, number
Sample response

A successful request returns 201 Created along with the created employee field object. The object contains the id, created_at, and updated_at attributes in addition to the mandatory attributes. The section_label attribute (in the response object) is the display name of the section corresponding to the section_name attribute passed in the request body.

Send employee portal invitation email

After creating an employee record in Freshteam, an organization sends an invitation email to the employee. The email serves to verify and activate the employee’s access to the employee portal. Through the portal, employees can maintain their employee information, access co-worker information, apply for time-offs, access the organization’s job postings, and so on.

The send_invite API identifies an employee object by the id passed in the request and sends the invitation email to employee.official_email.

put
/api/employees/{id}/send_invite
Path parameters
Parameter Name Data Type Description
idMandatory integer The employee.id value that is auto-generated when an employee’s details are configured in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
$ curl -X PUT "<account-name>/api/employees/3000145198/send_invite" 
            -H "accept: application/json"
            -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" 
            -H "Content-Type: application/json"
            -d "{"send_invite_email": true}"
EXPAND ↓
The request body parameter
Example 
1
2
3
{
    "send_invite_email": true
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
send_invite_email boolean A value of true specifies that the invitation email for the employee portal activation is to be sent to the employee.
Sample response

A successful request returns 200 OK along with the updated employee object.

Branches

For an organization, the offices in different geographic locations are its branches. The organization that uses Freshteam can configure various branches and associate employees to a branch.

Endpoint

GET /branches

The branch object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"id":3000011495,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-09-25T06:42:39.000Z",
"deleted":false,
"name":"Default - Head office",
"state":null,
"city":"Chennai",
"country_code":"IN",
"zip":null,
"time_zone":"Asia/Calcutta",
"currency":"USD",
"language":"en",
"main_office":true,
"date_format":"MonthFirst"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id number 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)

List all branches

Retrieves a list of all branches configured for the organization that uses Freshteam.

get
/api/branches
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/branches"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all branches’ details, as an array. Each array entry is a branch object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
 {
"id":3000011496,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-09-15T09:17:43.000Z",
"Deleted":false,
"name":"Branch office",
"State":null,
"city":"San Francisco",
"country_code":"US",
"zip":null,
"time_zone":null,
"currency":"USD",
"Language":"en",
"Main_office":false,
"date_format":"MonthFirst"
},
{"id":3000011495,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-09-25T06:42:39.000Z",
"Deleted":false,
"name":"Default - Head office",
"State":null,
"city":"Chennai",
"country_code":"IN",
"Zip":null,
"time_zone":"Asia/Calcutta",
"currency":"USD",
"Language":"en",
"Main_office":true,
"date_format":"MonthFirst"
}
]
EXPAND ↓

Departments

An organization is categorized into various departments based on the primary job roles in the organization. The high-level departments are further divided into sub-departments.

Endpoint

GET /departments

The department object

Example 
1
2
3
4
5
6
7
{
"id":3000126932,
"created_at":"2019-09-15T09:17:44.000Z",
"updated_at":"2019-09-15T09:17:44.000Z",
"Deleted":false,
"name":"Administration"
}
EXPAND ↓
Attributes
Attribute Name Data 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.

List all departments

Retrieves a list of all departments into which an organization is split.

get
/api/departments
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/departments"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all departments’ details, as an array. Each array entry is a department object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
  {
    "id": 3000126932,
    "created_at": "2019-09-15T09:17:44.000Z",
    "updated_at": "2019-09-15T09:17:44.000Z",
    "deleted": false,
    "name": "Administration"
  },
  {
    "id": 3000129089,
    "created_at": "2019-10-15T10:59:58.000Z",
    "updated_at": "2019-10-15T10:59:58.000Z",
    "deleted": false,
    "name": "Engineering"
  },
  {
    "id": 3000126931,
    "created_at": "2019-09-15T09:17:44.000Z",
    "updated_at": "2019-09-15T09:17:44.000Z",
    "deleted": false,
    "name": "Finance"
  },
  {
    "id": 3000126934,
    "created_at": "2019-09-15T09:17:44.000Z",
    "updated_at": "2019-09-15T09:17:44.000Z",
    "deleted": false,
    "name": "Human Resources"
  },
  {
    "id": 3000126930,
    "created_at": "2019-09-15T09:17:44.000Z",
    "updated_at": "2019-09-15T09:17:44.000Z",
    "deleted": false,
    "name": "Marketing"
  },
  {
    "id": 3000126933,
    "created_at": "2019-09-15T09:17:44.000Z",
    "updated_at": "2019-09-15T09:17:44.000Z",
    "deleted": false,
    "name": "Sales"
  }
]
EXPAND ↓

Sub-departments

In a Freshteam system, the various departments in an organization can be further classified into sub-departments and business functions.

Endpoint

GET /sub_departments

The sub-department object

Example 
1
2
3
4
5
6
7
{
      "id": 1,
      "created_at": "2019-07-05T10:04:56.000Z",
      "updated_at": "2019-07-05T10:04:56.000Z",
      "deleted": false,
      "name": "Freshteam"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id number Identifier of the sub-department object, auto-generated when a new sub-department is created in the Freshteam system.
created_at string Timestamp of when the sub-department is created, specified in the date-time format.
updated_at string Timestamp of when the sub-department’s name was last modified, specified in the date-time format.
deleted boolean Specifies whether the sub-department is still a valid categorization in the organization.
Possible values: true, false
name string Descriptive identifier of the sub-department.

List all sub-departments

Retrieves a list of all sub-departments into which a department is split.

get
/api/sub_departments
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/sub_departments"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all sub-departments’ details, as an array. Each array entry is a sub-department object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

1
2
3
4
5
6
7
8
9
[
    {
      "id": 1,
      "created_at": "2019-07-05T10:04:56.000Z",
      "updated_at": "2019-07-05T10:04:56.000Z",
      "deleted": false,
      "name": "Freshteam"
    }
  ]
EXPAND ↓

Business units

Business functions are the set of activities performed by the employees of an organization. In a Freshteam system, employees can be grouped into business units based on the business functions.

Endpoint

GET /business_units

The business unit object

Example 
1
2
3
4
5
6
7
8
{
"id":3000016570,
"created_at":"2019-10-15T10:59:58.000Z",
"updated_at":"2019-10-15T10:59:58.000Z",
"deleted":false,
"name":"DevOps",
"description":null
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the business unit object, auto-generated when a new business unit is created in the Freshteam system.
created_at string Timestamp of when the business unit is created, specified in the date-time format.
updated_at string Timestamp of when the business unit’s details were last modified, specified in the date-time format.
deleted boolean Specifies whether the business unit is still a valid business function in the organization.
Possible values: true, false
name string Descriptive identifier of the business unit.
Examples: Dev Ops, Web Ops, Engineering, and so on.
description string Description stating what the business function entails.

List all business units

Retrieves a list of all business units configured in the Freshteam system.

get
/api/business_units
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/business_units"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all business units’ details, as an array. Each array entry is a business unit object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

1
2
3
4
5
6
7
8
9
10
[
  {
    "id":3000016570,
    "created_at":"2019-10-15T10:59:58.000Z",
    "updated_at":"2019-10-15T10:59:58.000Z",
    "deleted":false,
    "name":"DevOps",
    "description":null
  }
]
EXPAND ↓

Teams

An organization forms various teams based on which employees can be grouped. The teams align to the various job functions the employees are expected to perform. An employee belongs to a primary team based on the employee’s primary job role and can be assigned to additional teams depending on the job profile.

Endpoint

GET /teams

The team object

Example 
1
2
3
4
5
6
7
{
      "id": 3000043460,
      "created_at": "2019-09-15T09:17:43.000Z",
      "updated_at": "2019-09-15T09:17:43.000Z",
      "deleted": false,
      "name": "Business"
}
EXPAND ↓
Attributes
Attribute Name Data 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.

List all teams

Retrieves a list of all employee teams configured for the organization that uses Freshteam.

get
/api/teams
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/teams"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all teams’ details, as an array. Each array entry is a team object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

1
2
3
4
5
6
7
8
9
10
11
12
13
[
{"id":3000043460,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-09-15T09:17:43.000Z",
"deleted":false,"name":"Business"
},
{"id":3000043467,
"created_at":"2019-09-15T09:17:44.000Z",
"updated_at":"2019-09-15T09:17:44.000Z",
"Deleted":false,
"name":"Corporate Marketing"
},
]
EXPAND ↓

Levels

The various job bands in an organization, which segregate the employees into a hierarchical structure, are the levels in the organization. The organization that uses Freshteam can configure levels and associate employees to a level.

Endpoint

GET /levels

The level object

Example 
1
2
3
4
5
6
7
{
"id":3000056483,
"created_at":"2019-09-15T09:17:44.000Z",
"updated_at":"2019-09-15T09:17:44.000Z",
"deleted":false,
"name":"IC1"
}
EXPAND ↓
Attributes
Attribute Name Data 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.

List all levels

Retrieves a list of all levels configured for the organization that uses Freshteam.

get
/api/levels
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/levels"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all levels’ details, as an array. Each array entry is a level object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
{
"id":3000056483,
"created_at":"2019-09-15T09:17:44.000Z",
"updated_at":"2019-09-15T09:17:44.000Z",
"deleted":false,
"name":"IC1"
},
{
"id":3000056484,
"created_at":"2019-09-15T09:17:45.000Z",
"updated_at":"2019-09-15T09:17:45.000Z",
"deleted":false,
"name":"IC2"
},
{
"id":3000056485,
"created_at":"2019-09-15T09:17:45.000Z",
"updated_at":"2019-09-15T09:17:45.000Z",
"deleted":false,
"name":"IC3"
}
]
EXPAND ↓

Timeoffs

An organization can use Freshteam for time-off management. Timeoff types are the vacation types that are available for the employees in the organization. An employee can raise leave of absence requests. The request details are grouped as timeoffs.

Endpoints

GET /time_offs
POST /time_offs
GET /time_off_types
GET /time_off_types/{id}

The timeoff object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"id":3000031566,
"created_at":"2019-09-15T09:18:44.000Z",
"updated_at":"2019-09-15T09:18:44.000Z",
"user_id":3000053373,
"start_date":"2019-01-01",
"end_date":"2019-01-04",
"status":"approved",
"leave_units":3,
"optional_leave_units":null,
"leave_type_id":3000011436,
"status_comments":null,
"approved_by_id":null,
"applied_by_id":3000053373,
"cancelled_by_id":null,
"rejected_by_id":null,
"comments":"Hospital appointment",
"rejected_at":null,
"cancelled_at":null
}
EXPAND ↓
Attributes

Attribute Name Data Type Description
id number Identifier of the timeoff object, auto-generated when a time-off request is saved.
created_at string Timestamp of when the time-off request is created, specified in the date-time format.
updated_at string Timestamp of when the time-off request details are last updated, specified in the date-time format.
start_date Mandatory string Starting date of the employee’s absence.
end_date Mandatory string Ending date of the employee’s absence.
status string Status of the time-off request.
Possible values (enum): pending, approved, declined, cancelled
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 Mandatory integer Identifier the time-off type under which the time-off request is raised. Must be a valid time_off_type.id value
status_comments string Reason for declining or cancelling the time-off request.
approved_by_id integer Identifier of the employee who approves the time-off request. Must be a valid employee.id value.
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.
rejected_by_id integer Identifier of the employee who declines the time-off request.
comments Mandatory 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.
cancelled_at string Timestamp of when the employee cancels the time-off request.
cancelled_due_to_exit boolean Specifies whether the time-off request is cancelled due to the off-boarding process of the employee.
The following attributes are returned as part of the response to the cancel timeoff and approve timeoff APIs.
attachment attachment object Details of the document attached to the time-off request, if the time-off type is configured to accept an attachment.
Attributes of the attachment object:
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.
leave_type timeoff type object Details of the type of time-off requested by the employee.
applied_by employee model objects Details of the employee who raises the time-off request.
approved_by employee model objects Details of the employee who approves the time-off request.
rejected_by employee model objects Details of the employee who rejects the time-off request.
cancelled_by employee model objects Details of the employee who cancels the time-off request.
user employee model objects Details of the employee who requires the time-off. Same as applied_by value, if the requestor raises the request.

The create timeoff object

Example 
1
2
3
4
5
6
7
8
9
10
{
  "start_date": "2019-11-15",
  "end_date": "2019-11-17",
  "optional_leave_days": [],
  "notify_to": [],
  "add_to_calendar": false,
  "auto_decline_events": false,
  "leave_type_id": 3000011437,
  "comments": "Personal work"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
start_date Mandatory string Starting date of the employee’s absence.
end_date Mandatory string Ending date of the employee’s absence.
optional_leave_days array of string Specifies the list of optional holidays that fall within the time-off request period, as an array. Each array entry is a date format value.
notify_to array of number Specifies the list of employees who are notified of the time-off request, as an array. Each array entry must be a valid employee.id value.
add_to_calendar boolean Specifies whether the time-off notice is added to the employee’s calendar automatically.
Valid values: true, false
auto_decline_events boolean Specifies whether all calendar events scheduled during the leave of absence are declined automatically.
Valid values: true, false
leave_type_id Mandatory integer Identifier of the time-off type under which the time-off request is raised. Must be a valid time_off_type.id value.
comments Mandatory string Reason for the time-off request.

The timeoff type object

Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"id":3000011437,
"created_at":"2019-09-15T09:18:43.000Z",
"updated_at":"2019-09-15T09:18:43.000Z",
"deleted":false,
"name":"Earned",
"description":"Earned Leave",
"applicable_for":null,
"default":true,
"auto_approve":false,
"auto_approve_after":null,
"auto_approve_limit":null,
"marital_status":null
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id number Identifier of the timeoff type object, auto-generated when a vacation type is configured.
created_at string Timestamp of when the time-off type is created, specified in the date-time format.
updated_at string Timestamp of when the time-off type details are last updated, specified in the date-time format.
deleted boolean Specifies whether the time-off type is still a valid vacation type in the Freshteam system.
Possible values: true, false
name Mandatory string Title of the time-off type.
description Mandatory 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 number Number of days after which a time-off request that is pending approval is auto-approved.
auto_approve_limit number 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

List all timeoffs

Retrieves a list of all time-off requests from all employees in the organization.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/time_offs
Query parameters

You can use a combination of the following query parameters to limit or filter the bulk response data.

Parameter Name Description Example
status Limits the response to time_off objects whose status value matches the parameter value.
Valid parameter values: pending, approved, declined, cancelled

GET /api/time_offs?status=pending
user Limits the response to time_off objects whose user_id value matches the parameter value.

GET /api/time_offs?user=3000053373
leave_type Limits the response to time_off objects whose leave_type_id value matches the parameter value.

GET /api/time_offs?leave_type=3000011436
location Limits the response to time-off requests that originate from a specific location, that is, requests from all employees whose branch.id value matches the parameter value. The employees are identified by applied_by_id.

GET /api/time_offs?location=3000011496
start_date Mandatory if the end_date filter is used. Limits the response to time_off objects whose start_date value matches the parameter value.

GET /api/time_offs?start_date=2019-09-17&end_date=2019-09-20
end_date Mandatory if the start_date filter is used. Limits the response to time_off objects whose end_date value matches the parameter value. Must be a value later than start_date.

GET /api/time_offs?start_date=2019-09-17&end_date=2019-09-20
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/time_offs"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all time-off requests from all employees, as an array. Each array entry is a timeoff object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request. The response header contains the pagination details. 

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
[
{"id":3000031566,
"created_at":"2019-09-15T09:18:44.000Z",
"updated_at":"2019-09-15T09:18:44.000Z",
"user_id":3000053373,
"start_date":"2019-01-01",
"end_date":"2019-01-04",
"status":"approved",
"leave_units":3,
"optional_leave_units":null,
"leave_type_id":3000011436,
"status_comments":null,
"approved_by_id":null,
"applied_by_id":3000053373,
"cancelled_by_id":null,
"rejected_by_id":null,
"comments":"Going to out of station to visit doctor",
"rejected_at":null,
"cancelled_at":null
},
{"id":3000031571,
"created_at":"2019-09-15T09:18:44.000Z",
"updated_at":"2019-09-15T09:18:44.000Z",
"user_id":3000053373,
"start_date":"2019-06-30",
"end_date":"2019-07-10",
"status":"approved",
"leave_units":7,
"optional_leave_units":null,
"leave_type_id":3000011437,
"status_comments":null,
"approved_by_id":null,
"applied_by_id":3000053373,
"cancelled_by_id":null,
"rejected_by_id":null,
"comments":"On vacation with family",
"rejected_at":null,
"cancelled_at":null
}
]
EXPAND ↓

Create a timeoff request

Creates a timeoff object based on the request body parameter. The request body parameter is a create timeoff object.

post
/api/time_offs
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
curl -X POST "https://<account-name>.freshteam.com/api/time_offs" -H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" -H "Content-Type: application/json"
-d '{
       "start_date": "2019-11-15",
 "end_date": "2019-11-17",
 "optional_leave_days": [],
 "notify_to": [],
 "add_to_calendar": false,
 "auto_decline_events": false,
 "leave_type_id": 3000011437,
 "comments": "To attend a family function"
}'
EXPAND ↓
Sample response

A successful request returns 201 Created along with the created timeoff object. The object contains the id, created_at, and updated_at attributes.

List all timeoff types

Retrieves a list of all vacation types configured for an organization.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/time_off_types
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/time_off_types"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all vacation types, as an array. Each array entry is a timeoff type object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
{"id":3000011437,
"created_at":"2019-09-15T09:18:43.000Z",
"updated_at":"2019-11-16T05:17:52.000Z",
"deleted":false,
"name":"Earned",
"description":"Earned Leave",
"applicable_for":null,
"default":true,
"auto_approve":false,
"auto_approve_after":null,
"auto_approve_limit":null,
"marital_status":null
},
{
"id":3000011436,
"created_at":"2019-09-15T09:18:43.000Z",
"updated_at":"2019-09-15T09:18:43.000Z",
"deleted":false,
"name":"Sick",
"description":"Sick Leave",
"applicable_for":null,
"default":true,
"auto_approve":false,
"auto_approve_after":null,
"auto_approve_limit":null,
"marital_status":null
}
]
EXPAND ↓

Retrieve timeoff information

Identifies a time-off request, by the id passed in the request and returns the corresponding information as a timeoff object.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/time_offs/{id}
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the timeoff object, auto-generated when a time-off request is generated.
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account-name>.freshteam.com/api/time_offs/3000039108" 
        -H  "accept: application/json" 
        -H  "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved timeoff object.

Cancel a timeoff request

Identifies a time-off object by the id passed in the request and cancels the corresponding time-off request by modifying the timeoff.status to cancelled. The time-off request can be cancelled by the person who raised the request. The request body parameter should be a valid JSON object of the specified format.

put
/api/time_offs/{id}/cancel
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the timeoff object, auto-generated when a time-off request is generated and returned as part of the response to a successful create timeoff request.
Sample request | Curl
Copied Copy 
1
2
3
4
curl -X PUT "https://<account-name>.freshteam.com/api/time_offs/3000111134/cancel" -H  "accept: application/json" 
    -H  "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" 
    -H  "Content-Type: application/json" 
    -d "{ }"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated timeoff object. The attributes cancelled_by and user will have the same value.

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
{
    "id":3000111134,
    "created_at":"2021-02-02T13:05:09.000Z",
    "updated_at":"2021-02-02T13:07:19.000Z",
    "user_id":3000058575,
    "start_date":"2021-06-29",
    "end_date":"2021-07-01",
    "status":"cancelled",
    "leave_units":3,
    "optional_leave_units":null,
    "leave_type_id":3000011437,
    "status_comments": “Rescheduled the personal appointment”,
    "approved_by_id":null,
    "applied_by_id":3000058575,
    "cancelled_by_id":3000058575,
    "rejected_by_id":null,
    "comments":"to pick up the parcel from store",
    "rejected_at":null,
    "cancelled_at":"2021-02-02T13:07:19.000Z",
    "cancelled_due_to_exit":false,
    "attachment":null,
    "leave_type":{
        "id":3000011437,
        "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":3000058575,
        "first_name":"Mia",
        "last_name":"l",
        "official_email":"m@frs.com"
    },
    "approved_by":null,
    "rejected_by":null,
    "cancelled_by":{
        "id":3000058575,
        "first_name":"Mia",
        "last_name":"l",
        "official_email":"m@frs.com"
    },
    "user":{
        "id":3000058575,
        "first_name":"Mia",
        "last_name":"l",
        "official_email":"m@frs.com"
    }
}
EXPAND ↓

Approve a timeoff request

Identifies a time-off object by the id passed in the request and approves the corresponding time-off request by modifying the timeoff.status to approved. The request body parameter should be a valid JSON object of the specified format.

Note: Only users in HR Partner, Admin, Reporting Manager, and Account Admin roles can access this API.

put
/api/time_offs/{id}/approve
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the timeoff object, auto-generated when a time-off request is generated and returned as part of a successful timeoff create request.
Sample request | Curl
Copied Copy 
1
2
3
4
5
curl -X PUT "https://<account-name>.freshteam.com/api/time_offs/3000111223/approve" 
    -H  "accept: application/json" 
    -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA" 
    -H  "Content-Type: application/json" 
    -d "{ }"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated timeoff object.

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
{
    "id": 3000111223,
    "created_at": "2021-02-04T06:16:51.000Z",
    "updated_at": "2021-02-04T06:20:49.000Z",
    "user_id": 3000140116,
    "start_date": "2021-02-10",
    "end_date": "2021-02-10",
    "status": "approved",
    "leave_units": "0.5",
    "optional_leave_units": null,
    "leave_type_id": 3000011436,
    "status_comments": "Approved",
    "approved_by_id": 3000140116,
    "applied_by_id": 3000140116,
    "cancelled_by_id": null,
    "rejected_by_id": null,
    "comments": "",
    "rejected_at": null,
    "cancelled_at": null,
    "cancelled_due_to_exit": false,
    "attachment": null,
    "leave_type": {
        "id": 3000011436,
        "deleted": false,
        "name": "Sick",
        "description": "Sick Leave",
        "applicable_for": "all",
        "default": true,
        "auto_approve": false,
        "auto_approve_after": null,
        "auto_approve_limit": null,
        "marital_status": "all"
        },
    "applied_by": {
        "id": 3000140116,
        "first_name": "Tinu",
        "last_name": "D",
        "official_email": "ti@frs.com"
        },
    "approved_by": {
        "id": 3000140116,
        "first_name": "Tinu",
        "last_name": "D",
        "official_email": "ti@frs.com"
        },
    "rejected_by": null,
    "cancelled_by": null,
    "user": {
        "id": 3000140116,
        "first_name": "Tinu",
        "last_name": "D",
        "official_email": "ti@frs.com"
        }
     }
EXPAND ↓

Roles

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.

Endpoint

GET /roles

The role object

Example 
1
2
3
4
5
6
7
8
{
 "id":3000060409,
 "created_at":"2019-09-15T09:17:43.000Z",
 "updated_at":"2019-11-09T06:00:07.000Z",
 "name":"Account Admin",
 "description":"Can Access \u0026 Modify the entire Freshteam account including  account and billing related information.",
 "default":true
}
EXPAND ↓
Attributes
Attribute Name Data 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

List all roles

Retrieves a list of all valid roles for the organization that uses Freshteam.

Note: Only users in HR Partner, Admin, and Account Admin roles can access this API.

get
/api/roles
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/roles"
-H "accept: application/json" -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all roles’ details, as an array. Each array entry is a role object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
{
"id":3000060409,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-11-09T06:00:07.000Z",
"name":"Account Admin",
"description":"Can Access and Modify the entire Freshteam account including account and billing related information.",
"default":true
},
{
"id":3000060410,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-11-09T06:00:07.000Z",
"name":"Admin",
"description":"Can Access and Modify all configurations in the Settings and will have complete access to all modules, but are restricted from Viewing Account and Billing settings.",
"default":true
},
{
"id":3000060416,
"created_at":"2019-09-15T09:17:43.000Z",
"updated_at":"2019-11-09T06:00:07.000Z",
"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
}
]
EXPAND ↓

Job postings

Freshteam enables organizations to create, publish, and monitor the job openings in the organization. Freshteam offers a default job posting form that helps to specify the information regarding a job opening. An organization can add custom fields to the default job posting form and tailor the form to cater to their specific needs. After creating a job posting, the organization can publish the posting to an internal career site or to external job boards. The job_postings APIs retrieve information pertaining to all or a specific job opening. The job_postings_fields API retrieves information about the fields on the job posting form.

Freshteam acts as a single point of reference to manage the requisitions and people (recruitment stakeholders and candidates) associated with a posting and monitor the status of the posting. Freshteam also provides a default applicant form, which can be attached to a job posting, to gather candidate information. In the capacity of an Applicant Tracking System (ATS) Freshteam helps to source candidates for a job opening and track their progress through the recruitment cycle. The applicant_fields API retrieves information about the fields on the applicant form.

Endpoints

GET /job_postings
GET /job_postings/{id}
GET /job_posting_fields
GET /job_postings/{id}/applicant_fields

The job posting object

Example 
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
{ 
    "id": 3000036107,
    "created_at": "2020-09-29T15:35:10.000Z",
    "updated_at": "2020-10-19T14:38:59.000Z",
    "deleted": false,
    "title": "Technical Support Engineer",
    "description": "<p>Published Job Description</p>",
    "status": "published",
    "salary": {
        "min": null,
        "max": null,
        "currency": "USD"
    },
    "applicant_access_type": "open",
    "remote": false,
    "show_pursue_as_career": false,
    "closing_date": null,
    "experience": "Entry Level",
    "type": "contract",
    "branch": {
        "id": 3000011495,
        "created_at": "2019-09-15T09:17:43.000Z",
        "updated_at": "2020-10-16T11:07:33.000Z",
        "deleted": false,
        "name": "Default - Head office",
        "state": "Tamilnadu",
        "city": "Chennai",
        "country_code": "IN",
        "zip": "600073",
        "time_zone": "Asia/Calcutta",
        "currency": "USD",
        "language": "en",
        "main_office": true,
        "date_format": "MonthFirst",
        "street": "Global Infocity, Perungudi"
    },
    "department": {
        "id": 3000129089,
        "created_at": "2019-10-15T10:59:58.000Z",
        "updated_at": "2019-10-15T10:59:58.000Z",
        "deleted": false,
        "name": "Engineering"
    }
    }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the job posting object, auto-generated when a new job posting is created in the Freshteam system.
created_at string Timestamp of when the job posting is created, specified in the date-time format.
updated_at string Timestamp of when the job posting is last updated, specified in the date-time format. If a job posting’s details are not updated, the updated_at and created_at values are the same.
deleted boolean Specifies whether the job posting is deleted from the Freshteam system.
Possible values: true, false
title string Name of the profile for which the organization is hiring.
description string Job details that specify requirements, responsibilities associated with the role, and so on.
status string Status of the job posting.
Possible values:
draft: Preliminary version of the job posting is saved but not published.
published: Job posting is published to the organization's career and employee portals and selected external job boards.
internal: Job posting is published only to the organization's employee portal.
private: Job posting is visible only to the hiring team and admins.
on_hold: Job posting is frozen and the organization is no longer accepting candidates for the job.
closed: Job requirement is met and the posting is closed.
applicant_access_type string Specifies the access restrictions to view the applicant information.
Possible values:
Open: All recruiters,hiring managers, and panel members assigned to the job posting can view details of all applicants.
Restricted: Only recruiters can view all details of all applicants.
show_pursue_as_career boolean Specifies whether an employee of the organization can apply for the job.
Possible values: true, false
closing_date string Target date by which the job requisition associated with the job posting should be filled.
experience string Level of experience required for the job role.
For example, Internship, Entry level, Associate, Mid-Senior level, Director/ Vice President, Executive/ President, and so on.
remote boolean Specifies whether the posting is for a remote job.
Possible values: true, false
type string Employment terms that apply to the job role.
For example, Full Time, Part Time, Contract, Internship, Temporary, Seasonal, Volunteer, and so on.
salary salary object Salary band defined for the job role.

Attributes of the salary object:
min (integer): Minimum salary payable for the job role.
max (integer): Maximum salary payable for the job role.
currency (string): Currency in which the compensation is payable, specified as a valid three-character ISO currency code.

branch branch object Details of the branch for which the job posting is created.
department department object Details of the department for which the organization is hiring.

List all job postings

Retrieves a list of all job postings configured in the Freshteam system.

get
api/job_postings
Query parameters

You can use a combination of the following query parameters to limit or filter the bulk response data. Ensure that the query parameter values are URL encoded.

Parameter Name Description Example
status Limits the response to job posting objects whose status value matches the parameter value.
Valid values: draft, published, internal, private, on_hold, closed

GET /api/job_postings?status=published
title Limits the response to job posting objects whose title value matches the parameter value.

GET /api/job_postings?title=Technical%20Support%20Engineer
type Limits the response to job posting objects whose type value matches the parameter value.

GET /api/job_postings?type=Contract
department Limits the response to job posting objects whose department.id value matches the parameter value.

GET /api/job_postings?department=3000000121
location Limits the response to job postings objects whose branch.id value matches the parameter value.

GET /api/job_postings?location=3000000742
remote Limits the response to job postings objects whose remote value matches the parameter value.
Valid values: true, false

GET /api/job_postings?remote=false
location_city Limits the response to job posting objects whose branch.city value matches the parameter value.

GET /api/job_postings?location_city=Chennai
location_country Limits the response to job posting objects whose branch.country_code value matches the parameter value.

GET /api/job_postings?location_country=IN
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/job_postings"
                -H "accept: application/json" -H "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all job postings’ details, as an array. Each array entry is a job posting object with the corresponding attributes. The response data is limited by the pagination parameters passed in the request. The response header contains the pagination details. 

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
[
    {
      "id": 3000042017,
      "created_at": "2021-01-04T05:17:13.000Z",
      "updated_at": "2021-01-04T05:17:13.000Z",
      "deleted": false,
      "title": "Technical Writer (Remote)",
      "description": "<p>Published Job Description</p>",
      "status": "draft",
      "salary": {
        "min": null,
        "max": null,
        "currency": "USD"
      },
      "applicant_access_type": "open",
      "remote": true,
      "show_pursue_as_career": false,
      "closing_date": null,
      "experience": null,
      "type": "full_time",
      "branch": {
        "id": 3000011495,
        "created_at": "2019-09-15T09:17:43.000Z",
        "updated_at": "2020-10-16T11:07:33.000Z",
        "deleted": false,
        "name": "Default - Head office",
        "state": "Tamilnadu",
        "city": "Chennai",
        "country_code": "IN",
        "zip": "600073",
        "time_zone": "Asia/Calcutta",
        "currency": "USD",
        "language": "en",
        "main_office": true,
        "date_format": "MonthFirst",
        "street": "Global Infocity, Perungudi"
      },
      "department": {
        "id": 3000126930,
        "created_at": "2019-09-15T09:17:44.000Z",
        "updated_at": "2019-09-15T09:17:44.000Z",
        "deleted": false,
        "name": "Marketing"
      }
    },
    {
      "id": 3000042005,
      "created_at": "2021-01-04T00:17:04.000Z",
      "updated_at": "2021-01-04T04:38:19.000Z",
      "deleted": true,
      "title": "Technical Writer (Remote)",
      "description": "<p>Published Job Description</p>",
      "status": "draft",
      "salary": {
        "min": null,
        "max": null,
        "currency": "USD"
      },
      "applicant_access_type": "open",
      "remote": true,
      "show_pursue_as_career": false,
      "closing_date": null,
      "experience": "Entry Level",
      "type": "full_time",
      "branch": {
        "id": 3000011495,
        "created_at": "2019-09-15T09:17:43.000Z",
        "updated_at": "2020-10-16T11:07:33.000Z",
        "deleted": false,
        "name": "Default - Head office",
        "state": "Tamilnadu",
        "city": "Chennai",
        "country_code": "IN",
        "zip": "600073",
        "time_zone": "Asia/Calcutta",
        "currency": "USD",
        "language": "en",
        "main_office": true,
        "date_format": "MonthFirst",
        "street": "Global Infocity, Perungudi"
      },
      "department": {
        "id": 3000126930,
        "created_at": "2019-09-15T09:17:44.000Z",
        "updated_at": "2019-09-15T09:17:44.000Z",
        "deleted": false,
        "name": "Marketing"
      }
    }
  ]
EXPAND ↓

Retrieve job posting information

Identifies a job posting, by the id passed in the request and returns the corresponding information as a job posting object.

get
api/job_postings/{id}
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the job posting object, auto-generated when a new job posting is created in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/job_postings/3000042150"
            -H "accept: application/json" -H "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved job posting object. For a job posting, if additional information is available in Freshteam, when retrieving the job posting’s information, the following additional attributes are returned as part of the response object.

Attribute Name Data Type Description
applicant_apply_link string URL through which the applicant can apply to the job role published across different job portals.
custom_field_values object The organization using Freshteam, can configure custom fields to define additional information about the job opening. 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 string Desirable skills expected from the candidates applying for the job role.
remote_branches array of branch objects All preferred locations that are specified when the job is listed in job portals.
requisitions array of objects Details of job requisitions associated with the job opening.

Attributes of the 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 value: true, false
title (string): Title of the job requisition, indicating the job role for which the requisition is created.
recruiters (array of employee model object): Details of employees associated with the requisition as recruiters.
hiring_managers (array of employee model object ): Details of employees associated with the requisition as hiring managers.
panel_members (array of employee model object): Details of employees associated with the requisition as the panel members who interview the candidates.

List all job posting fields

Retrieves a list of all default and custom job posting fields configured for an organization, in the Freshteam system.

get
api/job_posting_fields
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/job_posting_fields"
          -H "accept: application/json" -H "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all job posting fields’ details, as an array. Each array entry is a job posting field object with the corresponding attributes.

Example 
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
[	
    { 
    "id": 61093,
    "created_at": "2019-09-15T09:18:42.000Z",
    "updated_at": "2019-09-15T09:18:42.000Z",
    "job_form_id": 3000005915,
    "name": "title",
    "field_type": "text",
    "label": "Title",
    "position": 1,
    "default": true,
    "required": true,
    "public": true,
    "restricted": false
    },
    {
    "id": 61098,
    "created_at": "2019-09-15T09:18:43.000Z",
    "updated_at": "2020-07-23T14:45:45.000Z",
    "job_form_id": 3000005915,
    "name": "skills",
    "field_type": "dropdown",
    "label": "Skills",
    "position": 5,
    "default": true,
    "required": false,
    "public": true,
    "restricted": false
    },
    {
    "id": 61099,
    "created_at": "2019-09-15T09:18:43.000Z",
    "updated_at": "2020-07-23T14:45:45.000Z",
    "job_form_id": 3000005915,
    "name": "experience",
    "field_type": "dropdown",
    "label": "Experience",
    "position": 6,
    "default": true,
    "required": false,
    "public": false,
    "restricted": false
    },
    {
    "id": 61100,
    "created_at": "2019-09-15T09:18:43.000Z",
    "updated_at": "2020-07-23T14:45:45.000Z",
    "job_form_id": 3000005915,
    "name": "salary",
    "field_type": "object",
    "label": "Salary Details",
    "position": 7,
    "default": true,
    "required": false,
    "public": false,
    "restricted": false
    }
    ]
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the job posting field object, auto-generated when a new field is configured.
created_at string Timestamp of when the field is created, specified in the date-time format.
updated_at string Timestamp of when the field is last modified, specified in the date-time format.
job_form_id integer Identifier of the job posting form that the organization utilizes to publish job openings to the career portal and external job boards. The organization can add custom fields to the form in addition to the default fields.
name string Name of the job posting field. For custom fields, the field name is auto-generated based on the label specified.
label string Display name of the job posting field in the job posting form.
field_type string Type of the job posting field. The field types are predefined in the Freshteam system.
Possible values:
  • text
  • dropdown
  • email
  • phone_number
  • checkbox
  • paragraph
  • date_time
  • number
  • url_set
  • url
  • attachment
  • radio
  • label
position integer Placement of the job posting field in the job posting form. The numbering is from left to right and top to bottom.
required boolean Specifies whether the field is mandatory.
Possible values: true, false
default boolean Specifies whether the job posting field is a default field in the Freshteam system. For custom fields, the attribute value is false.
Possible values: true, false
public boolean Specifies whether the job posting field will be displayed in the career portal.
Possible values: true, false
restricted boolean Specifies the access restrictions to view the job posting field information.
Possible values: true, false
For example, if the value is true, only users with recruiter, admin, and account admin permissions can view the job posting field details.
picklist_values array of objects Details of the choices specified for a drop-down or radio field configured.

Attributes of the object:
id (integer): Identifier of the object, auto-generated when new choice is added to the Dropdown Items field when the choices are configured by using the Freshteam UI.
value (string): Name of the choice.
position (integer): Placement of the item in the drop-down list box or radio select field.
pickable_type (string): Details of the form in which the drop-down list box or radio select field is present. For example, the value job_form_fields indicates that the item specified is associated with the job posting form.
pickable_id (integer): Identifier of the job posting field to which the choice is associated.

List all applicant fields

An organization can attach a custom applicant form to a job posting, to collect information from applicants. This API identifies a job posting by the id passed in the request and returns the details corresponding to the fields of the associated applicant form.

get
api/job_postings/{id}/applicant_fields
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the job posting object, auto-generated when a new job posting is created in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
curl -X GET "https://<account-name>.freshteam.com/api/job_postings/3000042150/applicant_fields"
      -H "accept: application/json" -H "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all applicant field details, as an array. Each array entry is an applicant field object with the corresponding attributes.

Example 
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
[
    {
    "id": 3000900928,
    "created_at": "2021-01-07T08:18:46.000Z",
    "updated_at": "2021-01-07T08:18:46.000Z",
    "deleted": false,
    "applicant_form_id": 3000043207,
    "name": "first_name",
    "field_type": "text",
    "label": "First Name",
    "position": 1,
    "default": true,
    "group_label": null,
    "group_position": null,
    "group_name": null,
    "external_field": true,
    "recruiter_field": true,
    "vendor_field": true,
    "required_in_vendor_form": true,
    "viewable_by": "panel_member",
    "required_in_external_form": true,
    "required_in_recruiter_form": true,
    "base_model": "applicant"
    },
    {
    "id": 3000907498,
    "created_at": "2021-01-12T10:46:11.000Z",
    "updated_at": "2021-01-12T10:46:11.000Z",
    "deleted": false,
    "applicant_form_id": 3000043207,
    "name": "cf_custom_example",
    "field_type": "dropdown",
    "label": "Custom Example",
    "position": 8,
    "default": false,
    "group_label": null,
    "group_position": null,
    "group_name": null,
    "external_field": true,
    "recruiter_field": true,
    "vendor_field": true,
    "required_in_vendor_form": false,
    "viewable_by": "panel_member",
    "required_in_external_form": false,
    "required_in_recruiter_form": false,
    "base_model": "applicant",
    "picklist_values": [
    {
    "id": 3000020416,
    "value": "Choice 1",
    "position": 1,
    "pickable_type": "applicant_form_fields",
    "pickable_id": 3000907498
    },
    {
    "id": 3000020417,
    "value": "Choice 2",
    "position": 2,
    "pickable_type": "applicant_form_fields",
    "pickable_id": 3000907498
    },
    {
    "id": 3000020418,
    "value": "Choice 3",
    "position": 3,
    "pickable_type": "applicant_form_fields",
    "pickable_id": 3000907498
    }]
    }
  ]
EXPAND ↓
Attributes

Attribute Name Data Type Description
id integer Identifier of the applicant field object, auto-generated when a new field is configured as part of the applicant form.
created_at string Timestamp of when the field is created, specified in the date-time format.
updated_at string Timestamp of when the field is last modified, specified in the date-time format.
applicant_form_id integer Identifier of the applicant form in which the applicant field is present.
name string Name of the applicant field. This is a system generated value based on the field label.
label string Display name of the applicant field on the applicant form.
field_type string Type of the applicant field. The field types are predefined in the Freshteam system.
Possible values:
  • text
  • dropdown
  • email
  • phone_number
  • checkbox
  • paragraph
  • date_time
  • number
  • url_set
  • url
  • attachment
  • radio
  • label
  • employer
  • education

Note: The Employer and Education sections are available as part of the default applicant form to collect information from applicants about their employment and educational background. The field_type value of these sections are employer and education.

position integer Placement of the applicant field on the applicant form. The numbering is from left to right and top to bottom.
default boolean Specifies whether the applicant field is a default field in the Freshteam system. For custom fields, the attribute value is false.
Possible values: true, false
default boolean Specifies whether the job posting field is a default field in the Freshteam system. For custom fields, the attribute value is false.
Possible values: true, false
group_label string Display name of the group box to which the applicant field belongs, if a field of the section field_type is configured.
Currently, defining a field on the form with the field_type as section is not supported. So, group_label is null.
group_position string Placement of the group box on the applicant form.
Currently, defining a field on the form with the field_type as section is not supported. So, group_position is null.
group_name string Name of the group box to which the applicant field belongs.
Currently, defining a field on the form with the field_type as section is not supported. So, group_name is null.
external_field boolean Specifies whether the applicant field is included in the applicant form on the organization’s career portal.
recruiter_field boolean Specifies whether the applicant field is included in the form that recruiters use to add candidates to a job posting.
vendor_field boolean Specifies whether the applicant field is included in the form that vendors/sourcing partners use to add candidates to a job posting.
required_in_vendor_form boolean Specifies whether the applicant field is a mandatory field on the form that vendors use to add candidates to a job posting.
required_in_external_form boolean Specifies whether the applicant field is a mandatory field on the applicant form on the career portal.
required_in_recruiter_form boolean Specifies whether the applicant field is a mandatory field on the form that recruiters use to add candidates to a job posting.
base_model string Specifies whether the field holds information of an applicant directly assigned to the job posting or of a candidate/lead moved from the organization’s talent pool to the job posting.
Possible values: applicant, candidate
viewable_by string View permissions for the applicant field.
Possible values:
  • panel_member
  • hiring_manager
  • recruiter
    •

Default value: panel_member
For custom fields, the organization can modify the view permissions to provide access to only hiring managers or recruiters.

picklist_values array of objects Details of the choices specified for a drop-down or radio field configured in the applicant form.

Attributes of the object:
id (integer): Identifier of the object, auto-generated when new item is added to the drop-down list box.
value (string): Name of the item specified in the drop-down list box or radio list.
position (integer): Placement of the item in the drop-down list box or radio list.
pickable_type (string): Details of the form in which the drop-down list box or radio list is present. For example, the value applicant_form_fields indicates that the item specified is associated with the applicant form.
pickable_id (integer): Identifier of the applicant field with which the item specified is associated.

Create an applicant

Identifies a job posting by the identifier passed in the request and creates an applicant for the job posting, based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. The API can also be used to move an existing candidate from Freshteam’s generic talent pool to the identified job posting, as an applicant.

Note: Using Freshteam, an organization configures an applicant form. The applicant form is used to collect all information pertaining to a candidate who applies for a job posting. When a candidate/lead is moved from the organization’s generic talent pool to a job posting, as an applicant, the applicant information can consist of additional information. The List all applicant fields API retrieves all information pertaining to the fields of the applicant form. In the response object, the base_model attribute specifies whether a field is aligned to a job posting’s applicant information or the general talent pool’s candidate information. Any field with the base_model value as applicant can be used to construct the Create an applicant API’s request body parameter.

* The Content-Type should always be multipart/form-data for create/update requests with attachments.

post
api/job_postings/{id}/applicants
Path parameters
Parameter Name Data Type Description
idMandatory integer Identifier of the job posting object, auto-generated when a new job posting is created in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
6
7
curl -X POST "https://<account-name>.freshteam.com/api/job_postings/3000042192/applicants"
  -H  "accept: application/json"
  -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
  -H  "Content-Type: multipart/form-data"
  -F "candidate[first_name]=Test" -F "candidate[email]=testwq@email.com"
  -F "candidate[owner_id]=1" -F "candidate[source_category_id]=2"
  -F "candidate[resumes][]=@sample.csv"
EXPAND ↓
The request body parameter
Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "candidate": {
        "first_name": "Jack",
        "middle_name": "Walls",
        "last_name": "Smith",
        "email": "jackws@email.com",
        "mobile": "9810954323",
        "phone": "9810954323",
        "owner_id": 3000053373,
        "source_id": 3000084630,
        "source_category_id": 3000078215,
        "gender": "male"
                },
    "custom_fields": {},
    "candidate_id": ""
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
candidate applicant object Details of the candidate who is added as an applicant for a specific job posting.
custom_fields object 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.

Note: A List all applicant fields API call, retrieves all applicant fields configured in Freshteam to collect applicant information. In the retrieved response, the default attribute specifies whether a field is a custom field. Any of the valid custom fields can be used as part of the Create an applicant API’s request body parameter.
candidate_id integer Identifier of the candidate who is moved from the generic talent pool to a specific job posting, as an applicant.

To post an applicant who doesn’t exist in the talent pool, specify the candidate_id value as “ ”.

The List all Candidates API call retrieves a list of all candidates in the Freshteam’s talent pool. In the retrieved response, the id attribute identifies candidates. To move a candidate from the talent pool to a specific job posting, use this id value as the candidate_id value in the request body parameter.

Note: Currently, the List all Candidates API is under development. So, in the request body parameter, ensure that the candidate_id value is “ ”.

Attributes of the applicant object

Attribute Name Data Type Description
first_nameMandatory string Name of the applicant.
middle_name string Middle name of the applicant.
last_nameMandatory string Last name of the applicant.
emailMandatory string Email address of the applicant.
date_of_birth string Birth date of the applicant specified in the date format.
mobile string Mobile contact number of the applicant.
phone string Telephone contact number of the applicant.
source_idMandatory integer Identifier of the source through which the applicant information reaches the Freshteam system.
This is the source object.id value that is auto-generated when an application source is added to the Freshteam system.
source_category_idMandatory integer Identifier of the source category to which the source identified by source_id belongs.
This is the source category object.id value that is auto-generated when a source category is added to the Freshteam system.
profile_links array of objects Links to the social platforms that help showcase the applicant’s sample work. For example, Git, Dribble, Behance, Pinterest, Blog, Medium, so on.

Attributes of the array object:
name (string): Name of the social medium.
url (string): Link to the applicant's social medium handle.
location object Postal address of the applicant.

Attributes of the location object:
street (string): Street name, PO Box number, apartment complex, building identifier, or any other similar component of the applicant’s contact address.
city (string): City, district, town, or any other similar component of the applicant’s contact address.
state (string): State, region, province, county, or any other sub component of the applicant’s contact address.
country_code (string): Country to which the applicant belongs, expressed as a character code.
zip_code (string): ZIP or postal code.
skype_id string Official skype address of the applicant.
resumes array of files Resumes of the applicant.
cover_letters array of files Cover letters attached to the application.
portfolios array of files Content such as work samples that supplement the resumes and cover letters.

Attributes of the content file object

Attribute Name Data Type Description
idResponse attribute integer Identifier of the file uploaded as part of a job application.
content_file_name string Name of the file attached to the job application.
content_file_size string Size of the file.
description string Summary of the file contents.
url string Link to access the file.
Sample response

A successful request returns 201 Created along with the object created based on the request body parameters.

Example 
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
{
  "id": 3001379428,
  "created_at": "2021-02-19T08:18:38.000Z",
  "updated_at": "2021-02-19T08:18:38.000Z",
  "deleted": false,
  "status": "open",
  "job_id": 3000042192,
  "requisition_id": 3000042363,
  "custom_fields": {
    "cf_custom_example": null
    },
  "stage_id": 3000514574,
  "candidate": {
    "id": 3001335826,
    "eeo_veteran": null,
    "eeo_ethnicity": null,
    "eeo_disabled": null,
    "eeo_gender": null,
    "first_name": "Jack",
    "middle_name": "Wall",
    "last_name": "Smith",
    "email": "Jackws@email.com",
    "source_id": 3000084630,
    "source_category_id": 3000078215,
    "date_of_birth": null,
    "mobile": "9810954323",
    "phone": "9810954323",
    "profile_links": null
  }
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the applicant object, auto-generated when a new applicant is added to the Freshteam system's talent pool.
created_at string Timestamp of when the applicant is added to the Freshteam system`s talent pool, specified in the date-time format.
updated_at string Timestamp of when the applicant details is last updated, specified in the date-time format. For the create an applicant API, the updated_at and created_at values are the same.
deleted boolean Specifies whether the applicant information is deleted from the Freshteam system`s talent pool.
Possible values: true, false
gender string Gender of the applicant.
Possible values: true, false
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 integer Identifier of the job posting object that corresponds to the job opening for which the applicant is added to the candidate pool.
lead_id integer Lead identifier that is auto-generated and attached to the applicant information, when a candidate is added from the organization’s talent pool to a job posting’s candidate pool. This helps track the applicants progress through the recruitment cycle.
requisition_id integer Identifier of the job requisition object that specifies the details of job requisitions associated with the job opening.
profile_links array of objects List of various social platforms where applicant's work is displayed. For example, Git, Dribble, Behance, Pinterest, Blog, Medium, and so on.

Attributes of the array object:
name (string): Name of the social medium.
url (string): Link to the applicant's social medium handle.
custom_fields object 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.
stage_id integer Identifier of the hiring stage of the applicant, auto-generated when a stage is configured in Freshteam.
candidate applicant detail object Details of the applicant created based on the applicant object passed in the Create an applicant API request.
In addition to the attributes passed in the request, the following attributes are part of the applicant detail object.
If the Create an applicant API is used to move a candidate from the generic talent pool to a job posting, meaningful values are returned for the following attributes. Otherwise, the attributes contain default values.
Additional attributes of applicant detail object:
  • owner_id (integer): Identifier of the employee who is assigned as an owner for the job requisition. This is a valid employee.id value.
  • referred_by_id (integer): Identifier of the employee who referred the applicant. This is a valid employee.id value.
  • skills (array of strings): All skills specified for the applicant.
  • tags (array of strings): Meaningful tags added to the applicant’s profile.
  • eeo_ethinicity (string): Ethnicity of the applicant who is considered for the job on the basis of the EEO policy of the organization.
  • eeo_gender (string): Gender of the applicant who is considered for the job, on the basis of the EEO policy of the organization that enables providing equal opportunities to all genders.
  • eeo_veteran (string): Type of vetran applicant who is considered for the job on the basis of the Equal Employment Opportunity (EEO) policy of an organization that enables employing veterans from armed forces.
  • eeo_disabled (string): Specifies whether the applicant is considered for the job, on the basis of the EEO policy of the organization that enables employing people with disabilities.
  • resumes (array of content file object): Resumes of the applicant.
  • cover_letters (array of content file object): Cover letters attached to the application.
  • portfolios (array of content file object): Content such as work samples that supplement the resumes and cover letters.
The following fields contain default values. The fields are present for compatibility with in-development APIs to update the applicant information.
on_hold_at string Timestamp of when the application is moved to an on-hold status, specified in the date-time format.
on_hold_till string Date-time till when the application is marked to be on-hold.
rejected_at string Timestamp of when the application is moved to a rejected status, specified in the date-time format.
archived_at string Timestamp of when the application is moved to an archived status, specified in the date-time format.
moved_at string Timestamp of when the application is moved from its previous state to the current state, specified in the date-time format.

Candidate sources

Candidate source is the avenue through which a job application reaches an organization’s Freshteam system. Freshteam enables organizations to track the candidate source of all job applicants. This information is particularly useful in determining analytics data such as which source is the best at bringing in applicants who actually convert to employees. A source category is a meaningful grouping of sources. For example, sources such as Naukri, Monster, and Glassdoor can be grouped under the source category of Job Portals; Twitter and facebook can be grouped under the source category of Social. An organization cannot delete the default sources available in Freshteam; an organization can add additional sources to the existing list.

The candidate_sources APIs enable to create a custom source and retrieve all information pertaining to all default and custom sources configured in Freshteam.

Endpoints

GET /candidate_sources
POST /candidate_sources
GET ​/candidate_source_categories

The source object

Example 
1
2
3
4
5
6
7
8
9
{
    "id": 3000084630,
    "created_at": "2019-09-15T09:18:41.000Z",
    "updated_at": "2019-09-15T09:18:41.000Z",
    "deleted": false,
    "label": "Adzuna",
    "default": true,
    "leads_count": 9
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the source object, auto-generated when a new source is created in the Freshteam system.
created_at string Timestamp of when the source is created, specified in the date-time format.
updated_at string Timestamp of when the source is last updated, specified in the date-time format. If source.label of custom sources is not updated, the updated_at and created_at values are the same.
deleted boolean Specifies whether the source still exists in the Freshteam system.
Possible values: true, false
label string Name of the source.
default boolean Specifies whether the source is predefined in the Freshteam system.
For example, Facebook, Google Plus, LinkedIn, Twitter, FB page tab, Internal, Direct, and so on are the default sources.
Details of the default sources cannot be modified.
Possible values: true, false
leads_count integer Number of applicant profiles arriving into the Freshteam system through the particular source.

The source category object

Example 
1
2
3
4
5
6
7
8
9
{
    "id": 3000078215,
    "created_at": "2019-09-15T09:18:40.000Z",
    "updated_at": "2019-09-15T09:18:40.000Z",
    "deleted": false,
    "label": "Advertisement",
    "default": false,
    "leads_count": 8
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the source category object, auto-generated when a new source category is created in the Freshteam system.
created_at string Timestamp of when the source category is created, specified in the date-time format.
updated_at string Timestamp of when the source category is last updated, specified in the date-time format. If source category.label of custom source categories is not updated, the updated_at and created_at values are the same.
deleted boolean Specifies whether the source category still exists in the Freshteam system.
Possible values: true, false
label string Name of the source category.
default boolean Specifies whether the source category is predefined in the Freshteam system.
For example, Premium Job Boards, Social, Free Job Boards, Job Boards, Referral, Email, Portal, Referral - social, and so on are the default source categories in the Freshteam system.
Details of the default source categories cannot be modified.
Possible values: true, false
leads_count integer Number of applicant profiles arriving into the Freshteam system through the particular source category.

List all candidate sources

Retrieves a list of all sources configured in the Freshteam system.

get
/api/candidate_sources
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account-name>.freshteam.com/api/candidate_sources" 
        -H  "accept: application/json"
        -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all sources’ details, as an array. Each array entry is a source object with the corresponding attributes. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[ 
    {
    "id": 3000084630,
    "created_at": "2019-09-15T09:18:41.000Z",
    "updated_at": "2019-09-15T09:18:41.000Z",
    "deleted": false,
    "label": "Adzuna",
    "default": true,
    "leads_count": 9
    },
    {
    "id": 3000084623,
    "created_at": "2019-09-15T09:18:41.000Z",
    "updated_at": "2019-09-15T09:18:41.000Z",
    "deleted": false,
    "label": "Direct",
    "default": true,
    "leads_count": 12
    } 
]
EXPAND ↓

Create a candidate source

Creates a source object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/api/candidate_sources
Sample request | Curl
Copied Copy 
1
2
3
4
curl -X POST "https://<account-name>.freshteam.com/api/candidate_sources" 
    -H  "accept: application/json" 
    -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA" 
    -H  "Content-Type: application/json" -d '{  "label": "JobAgency"}'
EXPAND ↓
The request body parameter
Example 
1
2
3
{
"label": "JobAgency"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
label Mandatory string Name of the source to be created.
Minimum length: 2 characters
Maximum length: 128 characters
Sample response

A successful request returns 201 Created along with the created source object. The object contains the id, created_at, and updated_at attributes. As the information pertains to a newly created source, the leads_count value is 0.

1
2
3
4
5
6
7
8
9
{
  "id": 3000185680,
  "created_at": "2021-01-29T09:12:45.000Z",
  "updated_at": "2021-01-29T09:12:45.000Z",
  "deleted": false,
  "label": "JobAgency",
  "default": false,
  "leads_count": 0
}
EXPAND ↓

List all candidate source categories

Retrieves a list of all source categories configured in the Freshteam system.

get
/api/candidate_source_categories
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account-name>.freshteam.com/api/candidate_source_categories" 
        -H  "accept: application/json" 
        -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all source categories’ details, as an array. Each array entry is a source category object with the corresponding attributes. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[
    {
        "id": 3000078215,
        "created_at": "2019-09-15T09:18:40.000Z",
        "updated_at": "2019-09-15T09:18:40.000Z",
        "deleted": false,
        "label": "Advertisement",
        "default": false,
        "leads_count": 8
    },
    {
        "id": 3000078213,
        "created_at": "2019-09-15T09:18:40.000Z",
        "updated_at": "2019-09-15T09:18:40.000Z",
        "deleted": false,
        "label": "Agencies",
        "default": false,
        "leads_count": 5
    }
]
EXPAND ↓

User functions

A team that an organization defines in Freshteam comprises employees who perform specific functions. These functions are termed user functions. For example, each team can consist of user functions such as GTM, design, content, and so on.

Endpoints

GET /user_functions

The user function object

Example 
1
2
3
4
5
6
7
{
    "id": 490196,
    "created_at": "2019-11-12T10:29:28.000Z",
    "updated_at": "2019-11-12T10:29:28.000Z",
    "value": "design",
    "position": 6
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the user function object, auto-generated when a new user function is configured in the Freshteam system.
created_at string Timestamp of when the user function is created, specified in the date-time format.
updated_at string Timestamp of when the user function is last updated, specified in the date-time format. If a user function’s details are not updated, the updated_at and created_at values are the same.
deleted boolean Specifies whether the user function still exists in the Freshteam system.
Possible values: true, false
value string Descriptive identifier of the user function.
position integer Position of user function.value in the Function drop-down list from which a user function is selected for an employee.

List all user functions

Retrieves a list of all user functions configured in the Freshteam system.

get
/api/user_functions
Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account-name>.freshteam.com/api/user_functions" 
            -H  "accept: application/json" 
            -H  "Authorization: Bearer KszAL6WR2fM3yD4ZEgMXuA"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all user functions' details, as an array. Each array entry is a user functions object with the corresponding attributes. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
    {
        "id": 490196,
        "created_at": "2019-11-12T10:29:28.000Z",
        "updated_at": "2019-11-12T10:29:28.000Z",
        "value": "design",
        "position": 6
    },
    {
        "id": 490197,
        "created_at": "2019-11-12T10:29:28.000Z",
        "updated_at": "2019-11-12T10:29:28.000Z",
        "value": "gtm",
        "position": 1
    },
    {
        "id": 490198,
        "created_at": "2019-11-12T10:29:28.000Z",
        "updated_at": "2019-11-12T10:29:28.000Z",
        "value": "product ",
        "position": 5
    }
]
EXPAND ↓

New Hires

Freshteam facilitates a comprehensive employee on-boarding process. Organizations that use Freshteam add prospective employees (new hires) to a New Hire Queue. On-boarding the new hires includes sending information that would come handy for new hires on their joining day, sending pertinent documents, and sending a customized welcome email. After completing all on-boarding tasks, the organization can move new hires to an Onboarding Completed queue from which new hires can be added as employees of the organization.

Endpoints

POST /new_hires
GET /new_hires/{id}
PUT /new_hires/{id}

The new hire object

Example 
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
{
  "id": 3000145443,
  "created_at": "2021-02-08T05:16:26.000Z",
  "updated_at": "2021-02-08T05:16:26.000Z",
  "deleted": false,
  "eeo_ethnicity": null,
  "eeo_job_category": null,
  "id_card_details": null,
  "workstation_number": null,
  "work_numbers": [{
        "name": "Work",
        "number": "7826332634"
    }],
  "nick_name": null,
  "date_of_birth": "1997-05-29",
  "marital_status": null,
  "gender": "male",
  "blood_group": "A-",
  "emergency_contacts": null,
  "social_profiles": null,
  "address": {
        "street": "Rockville avenue",
        "city": "Chennai",
        "state": "TamilNadu",
        "country_code": "IND",
        "zip_code": "607001"
    },
  "phone_numbers": null,
  "communication_address": {
        "communication_street": "Woody street",
        "communication_city": "Chennai",
        "communication_state": "TamilNadu",
        "communication_country_code": "IND",
        "communication_zip_code": "607001",
        "same_as_residential": true
    },
  "designation": "Developer",
  "joining_date": "2020-02-10",
  "probation_start_date": "2020-02-10",
  "probation_end_date": "2020-08-10",
  "branch_id": 3000011495,
  "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,
  "termination_date": null,
  "termination_reason": null,
  "notice_period": null,
  "notice_start_date": null,
  "notice_end_date": null,
  "termination_category_id": null,
  "custom_fields": {
        "hobbies_cf_str01": null,
        "test_field_cf_str03": null,
        "payroll_id_cf_str04": null,
        "citizenship_cf_str02": {
            "id": 0,
            "value": null 
         }
    },
  "avatar_url": null,
  "first_name": "Jack",
  "middle_name": "L",
  "last_name": "Smith",
  "employee_id": "E001",
  "status": "hired",
  "official_email": "jack2345@gmail.com",
  "personal_email": "jack@new.com",
  "user_category": "onboarding",
  "employee_type": "full_time",
  "draft": false,
  "terminated": false,
  "hired_on": "2020-01-20",
  "no_show": false,
  "no_show_reason": null
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the new hire object, auto-generated when a new hire’s information is created. A successful create new hire request, returns this attribute as part of the response object. Further API requests can use the returned value to identify a new hire and update the new hire information.
created_at string Timestamp of when the new hire information is created, specified in the date-time format. The timestamp is returned as part of the response object, on successful processing of a new hire create request.
updated_at string Timestamp of when the new hire information is last updated, specified in the date-time format. If a new hire’s details are not updated, the updated_at and created_at values are the same.
deleted boolean Specifies whether the new hire’s employee record is deleted from the Freshteam system.
Possible values: true, 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.
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_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
    •
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.
designation string Job title of the new hire.
joining_date string Date when the new hire will join the organization, specified in the YYYY-MM-DD format.
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.
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.
business_unit_id string Identifier of the business function to which the new hire will belong, after joining the organization.
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.

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 string 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.
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.
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.
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 objects:
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 newhire object only if the attribute value is false.
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 new hire.
user_category string Category under which the new hire’s record qualifies to exist in Freshteam. For example, onboarding.
draft boolean If true, specifies that the new hire’s record is being drafted.
Possible values: true, false
terminated boolean If true, specifies that the new hire’s record is archived.
Possible values: true, false
The following attributes contain additional new hire information. For a new hire, if the additional information is available in Freshteam, when retrieving the new hire’s information, the following attributes are returned as part of the response object.
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_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.
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.
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 (string): The new hire has served in active duty in the armed forces.
  • Unprotected vetran (string): The new hire has not served in active duty but was involved in a campaign.
  • I don’t wish to answer (string)
secondary_last_name string Second surname of the new hire, if the new hire has a composite surname.
heriditary_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 current 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 string 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 number 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 number 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 number 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 number 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 number 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. When a new hire’s information is saved, if Naturalised is chosen as the Citizenship Status of the new hire, citizenship_status_id is 22.

designation string Job title of the new hire.
internship_end_date string Date when the new hire’s internship ends. This value is null for new hires who are not interns.
scheduled_weekly_hours number 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 number 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.
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.
retirement_status_id number 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.
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 boolean Primary language of the branch to which the new hire is associated.
time_zone boolean Time-zone applicable to the branch to which the new hire is associated.
The following attributes are embedded attributes. When retrieving a new hire’s information, you can use the include query parameter to retrieve these attributes as part of the response object.
branch branch object Branch to which the new hire belongs.
team team object Details of the primary employee group (team) 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 a new hire’s dependents, specified as an array of dependent objects.
business_unit business unit object Details of the business function to which the new hire belongs.
sub_department sub-department object Details of the sub-department 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.
reporting_to employee model object Details of the new hire’s reporting manager.
hr_incharge employee model object Details of the new hire's HR manager.
shift field option object Shift to which the new hire belongs. For example, Day shift, EMEA shift, and so on.
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 honour 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
user_function field option object Specific function that the new hire performs as part of a team. For example, GTM, design, and so on.
cost_center field option object Cost group to which the new hire belongs.
user_title field option object Title associated with the new hire. For example, Mr., Ms., and so on.
user_suffix_name field option object Name suffix associated with the new hire. For example, Jr., Sr., and so on.
user_honorary_suffix field option object Honorary title bestowed to the new hire. For example, OBE, MBE, and so on.
user_professional_suffix field option object Professional suffix associated with the new hire. For example, CFA, CPA, and so on.
user_academic_suffix field option object Academic qualification, which can be specified as a suffix, associated with the new hire. For example, M.S, Ph.D, and so on.
retirement_status field option object Retirement status associated with the new hire. For example, Retired, Voluntary retirement process, and so on.
citizenship_status field option object Citizenship status associated with the new hire. For example, Naturalised, By birth, and so on.
termination_category field option object Termination category under which the new hire oyee ceases to work for the organization. For example, Resignation, End of Contract, Involuntary, and so on.

Create a new hire

Creates a new hire object based on the information specified in the request body. The request body parameter should be a valid JSON object of the specified format.

post
/api/new_hires
Sample request | Curl
Copied Copy 
1
2
3
4
5
curl -X POST "https://<account-name>.freshteam.com/api/new_hires" 
        -H "accept: application/json" 
        -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" 
        -H "Content-Type: application/json" 
        -d '{ "first_name": "John", "last_name": "Smith", "personal_email": "john@freshteam.com", "joining_date": "2020-02-10" }'
EXPAND ↓
The request body parameter
Example 
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
{
  "first_name": "Jack",
  "middle_name": "L",
  "last_name": "Smith",
  "employee_id": "E001",
  "status": "hired",
  "official_email": "jack2345@gmail.com",
  "personal_email": "jack@new.com",
  "employee_type": "full_time",
  "work_numbers": [{
        "name": "Work",
        "number": "7826332634"
    }],
  "date_of_birth": "1997-05-29",
  "gender": "male",
  "blood_group": "A-",
  "address": {
        "street": "Rockville avenue",
        "city": "Chennai",
        "state": "TamilNadu",
        "country_code": "IND",
        "zip_code": "607001"
    },
  "communication_address": {
        "communication_street": "Woody street",
        "communication_city": "Chennai",
        "communication_state": "TamilNadu",
        "communication_country_code": "IND",
        "communication_zip_code": "607001",
        "same_as_residential": true
    },
  "designation": "Developer",
  "joining_date": "2020-02-10",
  "branch_id": 3000011495,
  "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,
  "custom_fields": {
        "hobbies_cf_str01": null,
        "test_field_cf_str03": null,
        "payroll_id_cf_str04": null,
        "citizenship_cf_str02": {
        "id": 0,
        "value": null
    }},
  "hired_on": "2020-01-20"
}
EXPAND ↓
Attributes
Attribute Name Data Type Description
first_name Mandatory string Business name of the new hire.
middle_name string Middle name of the new hire.
last_name Mandatory string Last name of the new hire.
personal_email Mandatory string Personal email address of the new hire.
joining_date Mandatory string Date when the new hire will join the organization, specified in the YYYY-MM-DD format.
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.
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.
designation string Job title of the new hire.
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.
business_unit_id string Identifier of the business function to which the new hire will belong, after joining the organization.
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.
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.
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.
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.
date_of_birth string Birth date of the new hire.
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-
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 newhire object only if the attribute value is false.
Sample response

A successful request returns 201 Created along with the created new hire object. The object contains the id, created_at, and updated_at attributes. In further API calls, the id that is returned can be used to update the corresponding new hire information or retrieve information.

Retrieve new hire information

Identifies a new hire by the id passed in the request and returns the corresponding information as a new hire object.

get
/api/new_hires/{id}
Path parameters
Parameter Name Data Type Description
idMandatory integer The new hire.id value that is auto-generated when a new hire’s details are configured in the Freshteam system.
Query parameters

To restrict the response (payload) object size, certain attributes are not specified as part of the new hire object by default. In the query string of the request URL, you can use the include query parameter, to retrieve the following new hire object’s attributes.

  • awards
  • honors
  • certificates
  • licenses
  • background_verification_details
  • visas
  • government_documents
  • dependents
  • bank_accounts
  • prev_employments
  • qualifications
  • compensation_details
  • bonuses
  • stocks
  • additional_teams
  • additional_managers
  • additional_hr_managers
  • languages
  • roles
  • team
  • branch
  • business_unit
  • sub_department
  • department
  • reporting_to
  • hr_incharge
  • level
  • shift
  • user_function
  • cost_center
  • user_title
  • user_suffix_name
  • user_honorary_suffix
  • user_professional_suffix
  • user_academic_suffix
  • retirement_status
  • citizenship_status
  • termination_category

Example to include branch in the response object:

GET /api/new_hires/6000053372?include=branch

Example to include branch and team in the response object:

GET /api/new_hires/6000053372?include=branch,team

Sample request | Curl
Copied Copy 
1
2
3
curl -X GET "https://<account-name>.freshteam.com/api/new_hires/6000053372" 
         -H "accept: application/json" 
         -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved new hire object.

Update new hire information

Identifies a new hire object by the id passed in the request and updates the object with the information specified in the request body. The request body parameter should be a valid JSON object of the specified format. If an attribute value is null or not passed as part of the request payload, the attribute’s existing value is retained.

put
/api/new_hires/{id}
Path parameters
Parameter Name Data Type Description
idMandatory number The new hire.id value that is auto-generated when a new hire’s details are configured in the Freshteam system.
Sample request | Curl
Copied Copy 
1
2
3
4
5
curl -X PUT "https://<account-name>.freshteam.com/api/new_hires/6000053372" 
        -H "accept: application/json" 
        -H "Authorization: Bearer D4HN6sD0qjUVI32cDCnQeQ" 
        -H "Content-Type: application/json" 
        -d '{ "first_name": "John", "last_name": "Sequiare", "personal_email": "john@freshteam.com", "joining_date": "2020-02-10" }'
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated new hire object.