Bulk Employees Download API (Early Access)

BalkanID Employees Download CSV Format

In this section, we will explain the BalkanID Employees CSV format.

Sample CSV

Employee ID	Full Name	First Name	Last Name	Work Email*	Department	Title	Start Date*	Employment Type	Manager	Manager Work Email	Source Employee ID	BalkanID Roles	Metadata Version	Metadata
1	Ahmed Ali	Ahmed	Ali	aali@example.com	Sales	Sales Representative	01/21/2021	Full-time	Maria Gomez	mgomez@example.com		reviewer, riskmanager, admin	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
2	Maria Gomez	Maria	Gomez	mgomez@example.com	Marketing	Marketing Manager	07/13/2020	Part-time	Ahmed Ali	aali@example.com	23	reviewer, admin	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
3	Xiaoyun Liu	Xiaoyun	Liu	xliu@example.com	IT	IT Analyst	01/01/2019	Contractor	Maria Gomez	mgomez@example.com		reviewer	v1	{"location": {"address": "1234 West Street, Office 112, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
4	Fatimah Al-Saud	Fatimah	Al-Saud	fasaud@example.com	HR	HR Coordinator	05/20/2019	Full-time	Ahmed Ali	aali@example.com	3251	reviewer	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
5	Pierre Dupont	Pierre	Dupont	pdupont@example.com	Operations	Operations Manager	08/15/2019	Full-time	Maria Gomez	mgomez@example.com		reviewer, admin	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "IJKLMNOP"}
6	Siti Fatimah	Siti	Fatimah	sfatimah@example.com	Finance	Financial Analyst	10/31/2019	Part-time	Ahmed Ali	aali@example.com		reviewer	v1	{"location": {"address": "1234 West Street, Office 113, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
7	Taro Yamada	Taro	Yamada	tyamada@example.com	Legal	Lawyer	01/01/2020	Full-time	Maria Gomez	mgomez@example.com		reviewer	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "IJKLMNOP"}
8	Nadezhda Ivanova	Nadezhda	Ivanova	nivanova@example.com	Engineering	Mechanical Engineer	03/15/2020	Contractor	Ahmed Ali	aali@example.com		reviewer	v1	{"\location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
9	Muhammad Khan	Muhammad	Khan	mkhan@example.com	Customer	Service	06/30/2020	Full-time	Maria Gomez	mgomez@example.com		reviewer	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
10	Sanjay Gupta	Sanjay	Gupta	sgupta@example.com	Research	Research Analyst	09/15/2020	Full-time	Ahmed Ali	aali@example.com		reviewer	v1	{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "ABCDEFGH"}

NOTE: Columns with * are required always.

Column Definitions

Column Name	Column Description
Employee ID	Required - A unique identifier for the employee. This is the internal balkan id of the employee
Full Name	One of Full Name, First Name, or Last Name required - The employee's full name. This is the recommended name field to use. In the sample CSV, this is: Ahmed Ali, Maria Gomez, etc.
First Name	One of Full Name, First Name, or Last Name required - The employee's first name. Using Full Name is recommended, but First Name can also be provided. In the sample CSV, this is: Ahmed, Maria, etc.
Last Name	One of Full Name, First Name, or Last Name required - The employee's last name. Using Full Name is recommended, but Last Name can also be provided. In the sample CSV, this is: Ali, Gomez, etc.
Work Email	Required - The work email of the employee. In the sample CSV, this is: aali@example.com, mgomez@example.com, etc.
Department	Optional - The employee's department. In the sample CSV, this is: Sales, Marketing, etc.
Title	Optional- The employee's job title. In the sample CSV, this is: Sales Representative, Marketing Manager, etc.
Start Date	Required - The employee's start date in MM/DD/YYYY format. In the sample CSV, this is: 01/21/2021, 07/13/2020, etc.
End Date	Optional - The employee's termination date, if any, in MM/DD/YYYY format. In the sample CSV, there are no End Dates listed, meaning everyone is still with the company.
Employment Type	Optional - The type of employment. In the sample CSV, this is: Full-time, Part-time, etc.
Manager	Optional - The full name of the employee's manager. In the sample CSV, this is: Maria Gomez, Ahmed Ali, etc.
Manager Work Email	Optional - The work email of the employee's manager. In the sample CSV, this is: mgomez@example.com, aali@example.com, etc.
Source Employee ID	Optional - A unique identifier for the employee from the source system. This can be a number or a string. In the sample CSV, this is 23, 3251, etc.
BalkanID Roles	Required - Roles of the Employee in the Balkan ID application. Can be - reviewer, riskmanager, admin
Organization	Optional - The organization the employee belongs to.
Metadata Version	Optional - The version for the Metadata. The only supported version as of now is v1. The Metadata fields supported in v1 are - location (json - address (string)), role id (string), employee (string), manager id (string), manager name (string), app (string), correlation id (string), tenant (string), timestamp (string). Even though the following fields are supported, they are meant for internal use and are only supported for the purpose of being able to download from an Employee integration (like Finch or Google) and then upload after edits to the Employee without losing relevant information about the original extraction from the integration - app (string), correlation id (string), tenant (string), timestamp (string).
Metadata	Optional - Metadata that is to be added to the Employee. This is a JSON object (see examples). Currently only Metadata of version v1 is supported.

Required Columns

Work Email and Start Date are always required.

One of Full Name, First Name, or Last Name are required. You may provide one, two, or all three of Full Name, First Name, or Last Name.

All other columns are optional.

Download the CSV file via the pre-signed URL

After retrieving the pre-signed URL in the previous step, all that remains is to download the CSV in BalkanID Employees CSV format from the pre-signed URL.
To use the polling URL, first send an HTTP request with the method HEAD to the pollingUrl.
If the response status code is 404, the file is not ready, and you should retry this polling request after a delay.
If the response status code is 200, the file is ready, and you may proceed to download the CSV from the received url.

application/json

download url response

Body

Download URL endpoint response

pollingUrl

string

required

The value is the polling URL which you will use to poll to find if the data is ready for download.

url

string

required

The value is the download URL from which you will download your CSV file.

Example

{
    "pollingUrl": "string",
    "url": "string"
}

Bulk Employees Download API (Early Access)

BalkanID Employees Download CSV Format

Sample CSV

Column Definitions

Required Columns

Download the CSV file via the pre-signed URL

Request

Request samples

Responses

Bulk Employees Download API (Early Access)

BalkanID Employees Download CSV Format#

Sample CSV#

Column Definitions#

Required Columns#

Download the CSV file via the pre-signed URL#

Request

Request samples

Responses

BalkanID Employees Download CSV Format

Sample CSV

Column Definitions

Required Columns

Download the CSV file via the pre-signed URL