Folks API
API Access Guidelines and Request - HRIS
This guide explains how to request and use your Folks HRIS API access. Two environments are available depending on your needs.
API Access Options
Sandbox
Test environment using fictitious data only. Ideal for developers and partners before moving to production.
Production
Access to your real data in Folks. Requires enhanced security measures and an approved request.
Request Procedure
- Choose your environment: Sandbox for testing, Production for live integration.
- Submit the request form specifying the type of access you need.
Once the feature is activated by Folks, an administrator can generate an API key via: Settings > Integrations > API Key Management
See also: Generate a Folks API Key
Security Considerations and Responsibilities
Once the API is activated, you can generate keys and define their permissions. These keys provide direct access to your data and must be handled with the same level of care as admin platform credentials.
As the platform operator, you are responsible for securing the generated keys as well as the administrator account used to create them. Any compromise of these accesses is your responsibility.
For the full terms of use: folksrh.com/termes-api
Excessive Usage
Clients are limited to 60 requests per minute. Exceeding this limit will result in a temporary block with a 403 Forbidden response.
If you have any questions, our support team is available to help.
Generate/Edit a Folks API Key
This article explains how to generate an API key in Folks.
If you do not have access to the API key management page, please ask our team to activate it. Only a company administrator can generate API keys.
|
When generating an API key, it will be marked V2. This is the new version of the API key, useful for employee modules and their personalized fields, time management and organizational structures (see Folks API Documentation). By default, the API key management page contains a V1 key. This key is used to access timesheet files and the ATS. This key can be updated as required from the company page. |
- In Folks, navigate to the API key management page (Admin > Company > API Key Management).
- In the top right-hand corner of the page, click Generate new API key.
- In the window that opens, give your API key a name and specify an expiration date, if desired.
- Under the Parameters section, you can activate the options for granting access to sensitive information (SIN, salary and banking information) and to employees' personal information.
- Under the Content of the API key section, you can select the desired access levels for employees, custom fields, absences, overtime, vacation, balances, positions, departments, working sites and admin (corresponds to all positions, departments and working sites).
- Click Generate. A message containing the unique identifier and the API key (secret key) will appear.
Warning! The key will only be displayed once. Copy it in a safe place so as not to lose it, then close the window.
You can edit the parameters of a V2 API key by clicking the ellipsisand selecting Edit. When you save your changes, all access tokens associated with the key will become invalid.
To delete a V2 API key, simply click the ellipsisand select Delete.
Create/Edit Custom Fields via API
Use the following operation to create (POST) or update (PUT) a custom field for the company or for a specific employee (see https://api.folkshr.app/api/documentation#/Custom%20Fields).
POST /api/v2/employees/{employee}/custom-fields
PUT /api/v2/employees/{employee}/custom-fields/{custom-fields-id}
When creating or editing a custom field, you can define a value as follows.
To define a value for a company custom field:
{
"employee_id": "null"
}To define a value for a custom employee field:
When a value is sent for an employee, if a value already exists, the existing value is overwritten.
{
"employee_id": "target_employee"
}The custom field value must respect the custom field type schema. When the value “null” is sent, the value associated with the custom field and the employee is removed.
- For an Alpha numeric custom field, a string must be supplied.
- For a Date custom field, a date in “YYYY-MM-DD” format must be supplied.
- For a Drop-down list custom field, the identifier of an option must be supplied.