Resources

Flat-File Integration

Synchronise your data between Biings and your HR systems.

Files structure

Welcome to our Flat-file documentation. If you are looking to synchronise your HR data with Biings you've come to the right place. Flat-File Integration (FFI) is based around completing an integration through the exchange of CSV text files. This documentation will help you format your data so that Biings can sychronize with your system. Depending on the products enabled for your account (Pilot and/or Notify), a set of up to 6 files can be synchronised with Biings. Files are linked together either through Persons ID or Org Units ID.

Synchronisation, history and initial import

Let's start with past data. The initial import, or first synchronisation, is used to setup your Biings account and populate it with the history of your HR data. This allows users to immediately recognise their team when they first log into Biings, and remove the need of having to duplicate things from your current HR system. We recommand the first set of CSV files to include the last 3 years of Absences, Persons, Assignments and Salaries data. A different history range is possible depending on your needs and data availability.


Once the initial set of data is imported, Biings uses daily synchronisation to keep data (absences, persons, salaries, etc) in sync with your HR system. Biings checks daily for new CSV files uploaded to your dedicated SFTP folder. If the file contains new or updated information, Biings will synchronise its database with it. Daily synchronisation uses the same CSV files, however the history should be limited in time (e.g. the last 3 months), depending on how far in the past you allow Absences (or other data) to be modified on your HR system.

N.B. Org Units and Occupations files should not include any history and simply reflect the current situation.

Example files

An example is worth a thousand words. Download our example files to quickly understand how files should be formated and how to relate them to one another.

We also support a single-file format limited to Persons and their job assignements.


Example pack

Download an example pack of 6 CSV files correctly related to one another.

Example pack  |  6 files

Single-file example

Download a single-file example. To be used when absence data synchronisation is not necessary.

Single CSV example

Files structure

Fields marked with a red "*" are required for the file to be accepted.
The entire record (CSV line) will be ignored if one of the required fields is empty or has the wrong format.

Fields marked with a yellow "*" are recommended for the use of Biings NOTIFY.
Recommended fields are mainly used to auto-fill insurance claim reports.

Absences file

Employees' absences including planned absences such as holidays and maternity leaves. An absence is defined as a period of time someone is away from work or unable to work.

Automatic Absence Consolidation
After each synchronisation Biings runs a consolidation algorithm on newly synchronised absences. This insures all absence-related analytics are accurate in regards to the original absence events. Please refer to our consolidation rules page to understand how and when Biings merges absences together.
Absence consolidation rules
Column Name Description Type Format
id * Unique absence identifier
• can be omitted for a single data import		 Int/String
person_id * Person identifier
• must match with an Id in the Person file		 Int/String
case_id Case identifier, grouping multiple absence together. Int
from * Date at which the work incapacity starts (e.g. 2021-10-27 07:30:00).
• date must be earlier or same date as end_date
• the "hh:mm" value is optional		 String yyyy-mm-dd hh:mm
until * Date at which the work incapacity ends.
• date must be later or same date as start_date
• an Empty value means the absence is still ongoing
• the "hh:mm" value is optional		 String yyyy-mm-dd hh:mm
time_due Minutes of work due, or missed, during the absence (e.g. 120).
• any kind of rates or time rules should already calculated (Biings will not apply any treatment to it and use the value as is)
• when provided, acts as a replacement to the standard calendar duration of the absence
• recommended for a more accurate absence rate computation		 Int
rate * Incapacity rate (rate at which the person is not at work).
• 1 means completly absent, 0.5 means 50% absent, etc.
• defaults to 1 if not provided		 Float Between 0 and 1
reason_id Unique identifier of the absence cause / reason of absence String / Int
reason * Absence reason/cause label (e.g. Sickness or Accident) String
planned Whether the absence is planned or not.
• NB: Sick-leaves are generally unplanned. Holidays are usually planned.		 Int 0: unplanned
1: planned
comment Any notes available about that particular absence (e.g. "Prefers to be contacted on his mobile phone.") String

Persons file

All persons/employees in your organisation with their personal details.

Column Name Description Type Format
id * Unique person identifier Int/String
lastname * Person's last name String
firstname * Person's first name String
gender * Gender of the person String F: Female
M: Male
N: Neutral
email * Professional email address String Email format
sso_account SSO account username String
avs_number * Swiss AVS number String 756.XXXX.XXXX.XY
phone_pro Professional phone number String Max 100 characters
phone_private * Private phone number String Max 100 characters
mobile_pro Professional mobile number String Max 100 characters
mobile_private Private mobile number String Max 100 characters
address_type Type of address (aka "address label") Int 2: Home
4: Office
address_note Note or complement to the address String
address_line1 * Address line 1 String
address_line2 Address line 2, if any String
address_line3 Address line 3, if any String
address_zip * Postal code String
address_city * City of residence String
address_country * Country code String ISO 3166-1 (alpha-2 or alpha-3)
birthdate * Date of birth Date yyyy-mm-dd
start_working_date Date the person first joined the company, or the hiring date Date yyyy-mm-dd
marital_status Current marital status Int 1: Single
2: Married
3: Divorced
4: Widow
5: Separated
6: Registered partnership
7: Dissolved partnership
9: Unknown
nb_children Number of dependent children Int
language * Communication language String ISO 639-1
nationality * Country code String ISO 3166-1 (alpha-2 or alpha-3)
zemis ZEMIS/SIMIC number
(for non-Swiss citizens)		 String
special_cases Special case of insurance Int 0: No particular case
1: Family member, partner
3: Optional insurance
with_holding_tax Whether subjected to holding-tax from the income source. Int 0: No
1: Yes, is subjected to holding-tax

Assignments file

Employees' job assignments, sometimes refered as "Work contracts". An assignment defines a moment in time (start and end) where the person has worked in your organisation, where (in which Org Unit) and at what percentage (rate).

A person can have more than one assignment at the same time provided that the total contract_rate does not exceeds "1" (100%).

Column Name Description Type Format
id * Unique Assignment identifier (recommended if available).
• if unavailable, Biings can generate the Id based on the combination of person_id + start_date + ou_id		 Int/String
person_id * Person identifier
• must match with an Id in the Person file		 Int/String
ou_id * Organisational Unit identifier
• must match with an Id in the Org Units file		 Int/String
start_date * Assignment start date
• date must be earlier or same date as end_date		 String yyyy-mm-dd
end_date * Assignment end date
• date must be later or same date as start_date
• an Empty value means the contract length is indeterminate		 String yyyy-mm-dd
rate * Work rate for this particular assignment Float Greater than 0,
Max 1
contract_rate Overall/Total work rate
In most situations a person is hired to fill only one position. In that case contract_rate and rate have the same value. When an employee fills more than one position (aka assignments), the contract_rate is the sum total of each of his/her assignment rates.		 Float Greater than 0,
Max 1
contract_status * Employment contract status. Int 0: Permanent
1: Fixed-term
job_id * Unique job/position identifier Int
job_function Job function or profession (e.g. project manager, nurse) String
job_custom_filter1 Additional job category (e.g. job family, career ladder). String
job_custom_filter2 Additional job category, if any. String
job_custom_filter3 Additional job category, if any. String
position * Person's professional position for this assignment. Int 1: Senior
2: Middle
3: Employee
6: Apprentice
7: Trainee
9: Unknown
regular_workplace Person's usual place of work for this assignment (e.g. office, shop). String
weekly_hours Expected working hours per week.
• if not provided, Biings will use the global weekly hours setting		 Float
frequency * Working frequency for this assignment. Int 0: Regular
1: Irregular
2: Short time
9: Unknown
vacation_days Number of days of vacation allowance per year.
• should be in relation to a 100% work rate (not pro-rated)
• if not provided, Biings will use the global vacation allowance setting		 Float

Salaries file *

Employees' salaries. One line defines the salary (or salary component) of a person for a given period of time.

Column Name Description Type Format
id * Unique Salary record identifier
• if unavailable, Biings can generate the Id based on the combination of person_id + amount + start_date		 Int/String
person_id * Person identifier
• must match with an Id in the Person file		 Int/String
code * Type of salary or benefit Int 100: basic/gross salary
101: LAA salary
102: LAAC salary
103: PGM salary
200: childs and family benefits
300: bonus or 13th salary
400: vacation and public holiday compensation
500: other supplements
amount * Salary amount Float
period * Frequency period at which the salary is paid. Int 1: hourly
2: daily
3: monthly
4: yearly
5: percentage
6: one time
start_date * Date at which the salary starts being effective.
• date must be earlier or same date as end_date		 String
end_date * Date at which the salary stops being effective.
• date must be later or same date as start_date
• an Empty value means the salary is always in effect. An end_date is required as soon as a new salary is in effect for that person.		 String
currency Currency used for the salary. String ISO 4217
e.g. CHF, EUR

Org Units file

All current Organisational Units (departments, services, teams, etc). This file is used to represent the organisational structure of your company. An Org Unit can be of any size or importance, either an entire department or a small team, it depends on the level of granularity you need.

  • This file should only include current Org Units, history should not be included.
  • Org Units with no parent_id will be considered as "top level" Org Units.
  • Biings supports multiple parallel organisational structures.
Column Name Description Type Format
id * Unique unit identifier Int/String
parent_id * Parent Unit identifier
• must match with the Id of another Org Unit in that same file		 Int/String
name * Org Unit name (e.g. Marketing, Human Resources, Production) String

Occupations file

All persons having a specific occupation or management role towards another person or group of persons. This file is used to describe the type of relations existing between every person (i.e. managers, HRBP, chiefs, substitute managers, etc).

  • Occupations are necessary to enable specific notification workflows and access controls.
  • This file should only include current Occupations, history should not be included.

You can choose to describe occupations by: A) specifing each individual Person-to-Person relation ; B) grouping a person's relations to all the persons within a specific Org Unit.

A) Person to Person:

Column Name Description Type Format
person_id * Person Id of the person the occupation is targeted to.
• must match with an Id in the Person file		 Int/String
to_person_id * Person Id of the person towards who the relation is (e.g. ID of the person's Manager).
• must match with an Id in the Person file		 Int/String
kind * Kind of relation Int 1: Substitute manager
2: Manager
4: RH

B) Person to Org Unit:

Column Name Description Type Format
person_id * Person Id of the person the occupation is targeted to.
• must match with an Id in the Person file		 Int/String
ou_id * The Org Unit ID with all the person towards who the relation is.
• must match with an Id in the Org Units file
• the person's occupation will be the same for all the persons inside that Org Unit		 Int/String
kind * Kind of relation Int 1: Substitute manager
2: Manager
4: RH