Bulk Employees Upload API (Early Access)

BalkanID Employees Upload CSV Format

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

Sample CSV

User ID	Full Name	First Name	Last Name	Work Email*	Department	Title	Start Date*	Employment Type	Manager	Manager Work Email	Source User 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
User ID	optional - A unique identifier for the user. This can be a number or a string. In the sample CSV, this is: 1, 2, 3, etc.
Full Name	One of Full Name, First Name, or Last Name required - The user'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 user'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 user'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 user. In the sample CSV, this is: aali@example.com, mgomez@example.com, etc.
Department	Optional - The user's department. In the sample CSV, this is: Sales, Marketing, etc.
Title	Optional- The user's job title. In the sample CSV, this is: Sales Representative, Marketing Manager, etc.
Start Date	Required - The user'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 user'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 user's manager. In the sample CSV, this is: Maria Gomez, Ahmed Ali, etc.
Manager Work Email	Optional - The work email of the user's manager. In the sample CSV, this is: mgomez@example.com, aali@example.com, etc.
Source	Optional - The source system from which the user data is imported.
Source User ID	Optional - A unique identifier for the user from the source system. This can be a number or a string. In the sample CSV, this is 23, 3251, etc.
BalkanID Roles	Optional - A comma-separated list of roles for the user. In the sample CSV, this is: reviewer, riskmanager, admin, etc.
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.
Delegate Name	Optional - The full name of the delegate who will act on behalf of this employee during their absence.
Delegate Email	Optional - The work email of the delegate. The delegate must already exist in the system.
Delegate Start Date	Optional - The date when the delegation starts in MM/DD/YYYY format.
Delegate End Date	Optional - The date when the delegation ends in MM/DD/YYYY format. If not provided, the delegation remains active indefinitely.
Delegation Reason	Optional - The reason for the delegation (e.g., "out of office", "vacation", "parental leave").

Note: Delegates should already be registered in the system before assigning them to users. Any users mapped to unrecognized delegates will be skipped during the upload.

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.

Upload the CSV file via the pre-signed URL

After retrieving the pre-signed URL in the previous step, all that remains is to upload the CSV in BalkanID Canonical CSV format to the pre-signed URL.
Below is a summary of the request using curl:

The request URL is the pre-signed URL from previous step.

The request method is PUT.

Required request body is the CSV in BalkanID Employees CSV format.

Bulk Employees Upload API (Early Access)

BalkanID Employees Upload CSV Format

Sample CSV

Column Definitions

Required Columns

Upload the CSV file via the pre-signed URL

Request

Request Code Samples

Responses

Bulk Employees Upload API (Early Access)

BalkanID Employees Upload CSV Format#

Sample CSV#

Column Definitions#

Required Columns#

Upload the CSV file via the pre-signed URL#

Request

Request Code Samples

Responses

BalkanID Employees Upload CSV Format

Sample CSV

Column Definitions

Required Columns

Upload the CSV file via the pre-signed URL