Folks API

Folks HR Webhooks

Webhooks allow Folks to automatically send information to an external system when an employee-related event occurs. They are used to capture these changes in real time to power integrations or automations.

Scope : webhooks are currently limited to the HRIS module and can only be managed by a company administrator. The feature must be activated by Folks.

Activation and access

  • If the feature is activated :
    Go to Settings > Integrations > Webhooks.
  • If the feature is not visible :
    contact Folks support or your Customer Success representative to request activation.

The Webhooks page becomes visible only to administrators once the company setting is activated.

Webhook configuration

The form for creating or modifying a webhook includes the following fields :

Field Description Required
Name Internal name of the webhook Yes
URL HTTPS endpoint receiving POST requests Yes
Enabled Enables or suspends webhook sending Yes
Events List of triggering events Yes (at least one)

Validation rules for the "Name" field

  • Required
  • Maximum length : 255 characters
  • Unique name (no duplicates allowed)
  • Must not end with a period (.)
  • Must not start or end with a space
  • Allowed characters : alphanumeric, space, hyphen (-), underscore (_)
  • Forbidden characters : < > : " / \ | ? *

Validation rules for the "URL" field

  • Required
  • Maximum length : 2000 characters
  • Must start with https://
  • localhost forbidden in production environment

Event selection

Each option in the interface corresponds to a type of event transmitted in the payload (value of the event field).

Interface event Value Description
Created employee.created New employee
Updated employee.updated Modification of an employee's data
Departure employee.offboarded Offboarding / deactivation
Return employee.returned Return after absence
Manager Assignment / Change employee.manager.assigned Newly assigned or modified manager
Status Change employee.status.changed Active, inactive, on leave, etc.

Note : if no event is selected, no webhook will be sent.

Payload structure

Webhooks send a JSON payload containing the following fields :

Field Required Description
event Yes Event type
employee_id Yes Folks identifier
email Yes Employee's work email
changes No Details of modified fields, in the format { old, new }
timestamp Yes Sent date and time (ISO 8601)
effective_date No Effective date of the change
source Yes Always folkshr
version Yes Payload format version (currently 1.0)
environment Yes Always production on the client side

Specificity : during the employee.created event, the payload contains all of the employee's data.

Payload example

{
  "event": "employee.updated",
  "employee_id": "F12345",
  "email": "jonathan.pelletier@mycompany.com",
  "changes": {
    "last_name": { "old": "PELETIER", "new": "PELLETIER" },
    "address_line1": { "old": "8 RUE ST-AUGUSTAIN", "new": "8 RUE ST-AUGUSTIN" },
    "mobile_phone": { "old": "418 932 3221", "new": "418 932 4221" }
  },
  "timestamp": "2025-08-11T14:32:00Z",
  "effective_date": "2025-08-11",
  "source": "folkshr",
  "version": "1.0",
  "environment": "production"
}

System behavior

  • Delivery : fire and forget model.
  • Retries : 3 attempts, spaced 2 minutes apart in case of failure.
  • Traceability : full logging history of sends (successes and failures).
  • Sensitive data protection : sensitive values in changes are masked by "*****".
  • Authentication : each request includes a mandatory authentication token, which the receiving system must verify.
  • environment field : internal informational field, always production for clients.
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
  1. Choose your environment: Sandbox for testing, Production for live integration.
  2. 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.
  1. In Folks, navigate to the API key management page (Admin > Company > API Key Management).
  2. In the top right-hand corner of the page, click Generate new API key.
  3. In the window that opens, give your API key a name and specify an expiration date, if desired.
  4. 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.
  5. 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).
  6. Click Generate. A message containing the unique identifier and the API key (secret key) will appear.
    _icon.svg 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 ellipsis8ce50461-7cf8-4ea7-984d-08ac0f2256f9and 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 ellipsis8ce50461-7cf8-4ea7-984d-08ac0f2256f9and 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.