Introduction
BitaBIZ API can be used for retrieving employees, registrations and other information from your BitaBIZ account to build your own reports.
In order to use and test the BitaBIZ API you will need to activate your company’s API key on your BitaBIZ account.
Click: Setup admin > Company > Subscription plan
💁 It requires Setup admin role to activate the API key
BitaBIZ API
The BitaBIZ API can return data in both JSON and CSV format depending on the query string URL you use in the API call:
Use JSON for REST method
Use CSV for Excel & PowerBI
REST
The REST API returns data in JSON format and have the following main query URL:
The REST API can be tested in a desktop tool like Postman.
In Postman you will need to add your company's API Key as x-apikey in the Headers section of your request:
Excel & PowerBI
The Excel & PowerBI API returns data in CSV format and have the following main query URL:
Use the BitaBIZ Excel & PowerBI API to create your own reports.
Insert the query URLs you are going to use in PowerBI or Excel.
API documentation
Employees
To get all employees including their master data in your company use this URL:
REST:
HTTP Method GET https://registrations.api.bitabiz.com/v2/employees/
Excel & PowerBI:
The employees URL returns the following master data information:
BitaBIZ name/ID | API name/ID | Description |
| Guid | Unique employee identification, with this id several reports can be joined. |
First name Last name | Name | First name and last name |
First name Middle name Last name | Full name | First name, middle name, last name |
Department | Department |
|
P-Number | pNumber | P number for DST (Denmark Statsistics reporting) |
Job Title | JobTitle |
|
Employee number | EmployeeId | Internal company id |
Payroll number | EmployeePayrollId | Payroll id used by an external payroll system.(Format can be numbers, letters or a combination of both) |
Office location | Country.Name | Office location tag |
Country/region/calendar group | Country.Region | Country, region and calendar group tag |
Group Company | Group.Company | Group company tag |
PersonalInfo.Email |
| |
Birthday | PersonalInfo.Birthdate |
|
Mobile number | PersonalInfo.Mobile |
|
Date of employment | Employment.Start |
|
| Employment.End | Date of termination for inactive employees |
| LastLogin |
|
| Active | By default, only active users are shown - add this attribute to the URL to get both active and inactive users: ?inactive=true |
Link between BitaBIZ employee master data and the API:
Employee master data include policy settings the employee is attached to:
BitaBIZ name/ID | API ID | Description |
| SalaryAgreement.Id |
|
Policy | SalaryAgreement.Name |
|
Working week | SalaryAgreement.WorkingDays | Monday-Friday (5) or other work week (7) |
Work week -> Work hours per week | SalaryAgreement.HoursPerWeek | Sum of standard work hours per week |
Vacation days/ year | SalaryAgreement.VacationDays | Does not include any adjustments or vacation taken |
Other Vacation days/ year | SalaryAgreement.OtherVacationDays | Does not include any adjustments or other vacation taken |
Week day name | SalaryAgreement.WeekDaysCsv.weekDay[x]English | Week day 1 = Monday. Week day 2 = Tuesday. etc. |
Standard work hours per week day | SalaryAgreement.WeekDaysCsv.weekDay[X] | Week day 1 = Standard hours on a Monday. Week day 2 = standard hours on a Tuesday. Etc.
|
Standard work hours per week day for secondary week. | SalaryAgreement.WeekDaysCsv.weekDay[X]secondaryHours | Week day 1 = Secondary hours on a Monday. Week day 2 = Secondary hours on a Tuesday. Etc. |
Standard work start time on week day | SalaryAgreement.WeekDaysCsv.weekDay[X]start | Week day 1 start = Standard work start time (eg. 8:00) |
Standard work end time on week day | SalaryAgreement.WeekDaysCsv.weekDay[X]end | Week day 1 end = Standard work end time (eg. 16:00) |
Standard work start time for secondary week day | SalaryAgreement.WeekDaysCsv.weekDay[X]secondaryStart | Week day 1 secondary start = Standard work start time (eg. 7:00) |
Standard work end time for secondary week day | SalaryAgreement.WeekDaysCsv.weekDay[X]secondaryEnd | Week day 1 secondary end = Standard work end time (eg. 15:00) |
Vacation factor for payroll system | SalaryAgreement.VacationFactor | Payroll 1:1 (Full time). Payroll 1:1.25 (Part time 4 working daysFull time). Etc. |
Salary part code for vacation for payroll system | SalaryAgreement.VacationCode | Code for export to external payroll system. |
Salary part code for Other vacation for payroll system | SalaryAgreement.otherVacationCode | Code for export to external payroll system. |
Salary part code for Sick Leave for payroll system | SalaryAgreement.sickCode | Code for export to external payroll system. |
Salary part code for Child sick leave for payroll system | SalaryAgreement.childSickCode | Code for export to external payroll system. |
Seconday work week applies to odd or even weeks. | SalaryAgreement.WeekRule | "Even" = Standard work hours for secondary week applies to even weeks, ie. week 20. "Odd" = Standard work hours for secondary week applies to odd weeks, ie. week 21. |
Breaks | salaryAgreement.BreaksCSV | List of active breaks on employee's policy, ie: "12:00-12:30, 14:00-15:30"
|
Employee's timezone | Timezone | Timezone : “(GMT+01:00) Amsterdam,…” |
Payroll, Employee and HR tags | Tags | "Payroll"="ADSL", |
Approver(s) | Approvers | Email of approver(s) for employee. If employee is selfapprover approver is shown as "selfapprover". |
Link between BitaBIZ policy settings and the API:
Employees / NationalHolidays
This URL request is for getting bank holidays for all employees in a company in a given period.
REST:
HTTP Method GET
Excel & PowerBI:
Optional parameters:
from = yyyy-MM-dd, to = yyyy-MM-dd
Examples:
National holidays returns the following information:
BitaBIZ name/ID | API ID | Description |
| Guid | Unique employee identification, with this id several reports can be joined. |
First Name Last name | Name | First name and last name. |
| SumOfDays | Sum of national holidays in days in a period. |
| SumOfHours | Sum of national holidays in hours according to the employee's daily work hours. |
| HolidaysCount | Count of national holidays in a period. |
Add holidays > Holiday name | Holidays.Description | Name of national holiday ie "New Year's Eve". |
| Holidays.StartDate |
|
| Holidays.EndDate |
|
| Holidays.DayOfWeek | Name of a day (Monday-Sunday). |
| Holidays.SumDays | Value in days can be 1 for full-day or 0.5 for half-day. |
| Holidays.SumHours | Value in hours according to employee hours per day. |
Registrations
Getting registrations for the whole company in a period specified.
REST:
HTTP Method GET
Excel & PowerBI:
Optional parameters:
from = YYYY-MM-dd, to = YYYY-MM-dd
reason = comma-separated reason codes, please see our table of possible reason codes
status = comma-separated status codes, please see our table of possible status codes
💁 Please note that calling the queries below from PowerBI will response with a .csv format:
The .csv is basically one column that needs to be split out into new columns and rows.
Therefore add these steps in the PowerBI query to get the correct columns.
1. = Csv.Document(Web.Contents(the url query that you want to use),[Delimiter=",", Columns=30, Encoding=65001, QuoteStyle=QuoteStyle.None])
----- this will return 30 columns
2. = Table.ReplaceValue(Source,"registrations.","",Replacer.ReplaceText,{"Column1", "Column2", "Column3", "Column4", "Column5", "Column6", "Column7", "Column8", "Column9", "Column10", "Column11", "Column12", "Column13", "Column14", "Column15", "Column16", "Column17", "Column18", "Column19", "Column20", "Column21", "Column22", "Column23", "Column24", "Column25", "Column26", "Column27", "Column28", "Column29", "Column30"})
3. = Table.PromoteHeaders(#"Replaced Value", [PromoteAllScalars=true])
Examples:
Registrations include the following information and columns:
BitaBIZ name/ID | API ID | Description |
| Guid |
|
First name Last name | Name | The name saved to an registration is saved historically. For exampel, if employee last name changes this change will not change the name attached to a saved registration.
If name on registrations should change accourding to changes to an employee name get emplyee name from /employees.
|
| Registration.Spanned | Can be TRUE if spanning over several days |
| Registration.SpannedDay | When the registration consists of several days - this would be the count of the day. 0 is the first day in spanned registration. |
| Registration.Date |
|
| Registration.TimeStart |
|
| Registration.TimeEnd |
|
| Registration.Amount.Days | Value in days if relevant for registration type |
| Registration.Amount.Hours | Value in hours if relevant for registration type |
| Registration.Amount.Km | Value in km if relevant for registration type |
| Registration.Amount.Unit | Default unit or a combination (days and hours) |
| Registration.DateDetails.Week | Week number |
| Registration.DateDetails.Weekday | Day number of the week (1 - Monday) |
| Registration.DateDetails.WeekDayEnglish | Name of the day of the week |
| Registration.DateDetails.Holiday | True if the registration overlaps national holiday |
| Registration.DateDetails.HolidayDetails.Description | Name of the national holiday that is overlapped |
| Registration.Type | Vacation, Other vacation, Child sick, Sick, Out of office, Overtime, Time off, Leave, Mileage |
| Registration.Subtype | Subtype - are 1/a job code for Time and Overtime registrations, or 2/ Subtypes to specify registrations in more detail, like e.g. other absence. |
| Registration.Reason | BitaBIZ reason codes: HH = Vacation HF= Other vacation (Customizable name) IS= Sick IC= Child sick L= Other absence/Leave (Customizable name) P= Own types VO: Overtime (Customizable name) VT: Time off (Customizable name) TT: Time MI: Milage FT: Flextime (Customizable name) DO: Day bank plus day (Customizable name) DT: Day bank minus day (Customizable name) RHH: Payout Vacation RHF: Payout Other vacation RVT: Payout Hour Bank RDT: Payout Day bank |
| Registration.Created | Timestamp of when the registration got created |
| Registration.Note | A note added to a registration - Notes for Sick registrations are never shown to other than employee and Approver |
| Registration.OfficeStatus | The out of office status associated with the registration: “Free”/ ”Busy”/ ”Out of office” |
| Registration.JobCode.Id | Jobcode id for integration to other payroll systems |
| Registration.JobCode.IsPayroll | TRUE/FALES - if true registration is to be processed by an external payroll system |
Registrations / employee
Getting registrations for a single employee.
Same parameters can be applied as in the registration endpoint above.
REST:
HTTP Method GET
Excel & PowerBI: https://registrations.api.bitabiz.com/pbi/INSERT_API_KEY_HERE/registrations/INSERT_EMPLOYEEGUID_HERE
Attributes in API queries
Attributes are URL parameters. The standard attribute is for example "from" and "to". Parameters can be combined while the first parameter starts with ? other additional parameters are added with &
Examples:
FROM and TO parameter
"From" and "to" need to have a value in this format YYYY-MM-dd. It is also possible to use literal like
?from=2019-01-01&to=2019-12-31
?from=lastXXmonths.
Examples:
loads results between today and the same date 2 years ago.
STATUS Parameter
In BitaBIZ, registration can have 5 different status types.
APP = approved
PEN = pending
REJ = rejected
DEL = deleted
CHK = checked in
By default only registrations with status=app (approved) are shown. If you need to add other registration status, separate values with comma. Status=app,pen,rej,chk
Status "CHK" are Flex and Time registrations that are currently only checked in and not yet checked out.
Examples:
Returns all pending registrations in a period.
REASON Parameter
BitaBIZ has over 10 different registration types. It is possible to filter out only certain registration types or combine two or more types. These parameters are not case sensitive, so both variations like ‘hh’ and ‘HH’ will work. Without the reason parameter being present, all registration types are returned.
Combination examples:
Registration types
Sick day registrations (Reason=IS)
Colum in Excel | Amount | Weekend | Holidays | Day off |
registrationAmontDays | Days | Count registration 0 if weekend | Count registration 0 if holiday | Count registration 0 if day off |
registrationAmontHours | Hours (look at standard work hours for hour amount) | - | - | - |
Child sick (Reason=IC)
Amount colum in Excel | Weekend | Holidays | Day off |
registrationAmontDays | Count registration 0 if weekend | Count registration 0 if holiday | Count registration 0 if day off |
registrationAmontHours | - | - | - |
Vacation (Reason=HH)
Other vacation (Reason=HF)
Leave (Reason=L)
Own types (Reason=P)
Overtime (Reason=VO)
Time off (Reason=VT)
Time (Reason=TT)
Mileage (Reason=MI)
Daybank – plusdays (Reason=DO)
Daybank - minus days (Reason=DT)
FLEX (Reason=FT)
Payout of Hour bank hours (Reason = RVT)
Payout of Day bank days (Reason = RDT)
Payout of Vacation days (Reason = RHH)
Payout of Other vacation hours/days (Reason = RHF)