Developer Hub
Request Demo
Request Demo
Support
  1. Employees
  • Getting Started
    • Introduction
  • API Reference
    • Admins
      • Bulk Admins Download API
    • Business Owners
      • Bulk Business Owners Download API
      • Bulk Business Owners Upload API
    • Configuration
      • Bulk Entity Finding Rules Download API
      • Bulk Custom Insights (Entity Rules) Download API
      • Bulk Filters Download API
      • Bulk Findings Download API
      • Get Branding Information
    • Employees
      • Bulk Employees Download API
        POST
      • Bulk Employees Upload API
        POST
    • Entitlements
      • Bulk Entitlements Download API
      • Bulk Entitlements Upload API
    • Entities
      • Bulk Entities Download API
      • Bulk Entities Upload API
      • Bulk Entities + Entity-Relations Zip Upload API
    • EntityInsights
      • Bulk Entity Insights Download API
    • EntityRelations
      • Bulk Entity Relations Download API
      • Bulk Entity Relations Upload API
    • EntityRBAC
      • Bulk Entity RBAC Download API
    • Integrations
      • Bulk Integrations Download API
    • Purposes
      • Bulk Purposes Download API
    • Relations
      • Bulk Relations Upload API
    • Requests
      • Bulk Requests Download API
    • Reviews
      • Bulk Reviews Download API
  • Relations
    • Bulk Employee Relations Upload API
      POST
    • Bulk Employee Relations Download API
      POST
  • Schemas
    • Schemas
      • AdminsDownloadURLRequest
      • BusinessOwnersDownloadURLRequest
      • EntitiesDownloadURLRequest
      • EntitiesUploadURLRequest
      • EntitlementDownloadURLRequest
      • EntitlementUploadURLRequest
      • EntityRelationsDownloadURLRequest
      • EntityRelationsUploadURLRequest
      • Error
      • FindingsDownloadURLRequest
      • UploadURLResponse
    • DownloadURLResponse
    • EmployeeRelationsDownloadURLRequest
    • ReviewDownloadURLRequest
    • RequestsDownloadURLRequest
    • EntitiesBulkUploadURLRequest
    • Logo
    • BrandingResponse
  1. Employees

Bulk Employees Download API

POST
https://balkanid.app/api/rest/v0/employees/download-url

BalkanID Employees Download CSV Format#

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

Sample CSV#

User IDFull NameFirst NameLast NameWork Email*DepartmentTeamTitleStart Date*End DateEmployment TypeManagerManager Work EmailSource User IDBalkanID RolesMetadata VersionMetadata
1Ahmed AliAhmedAliaali@example.comSalesEnterpriseSales Representative01/21/2021Full-timeMaria Gomezmgomez@example.comreviewer, riskmanager, adminv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
2Maria GomezMariaGomezmgomez@example.comMarketingBrandMarketing Manager07/13/2020Part-timeAhmed Aliaali@example.com23reviewer, adminv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
3Xiaoyun LiuXiaoyunLiuxliu@example.comITHelpdeskIT Analyst01/01/2019ContractorMaria Gomezmgomez@example.comreviewerv1{"location": {"address": "1234 West Street, Office 112, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
4Fatimah Al-SaudFatimahAl-Saudfasaud@example.comHRTalentHR Coordinator05/20/2019Full-timeAhmed Aliaali@example.com3251reviewerv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
5Pierre DupontPierreDupontpdupont@example.comOperationsLogisticsOperations Manager08/15/2019Full-timeMaria Gomezmgomez@example.comreviewer, adminv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "IJKLMNOP"}
6Siti FatimahSitiFatimahsfatimah@example.comFinanceTreasuryFinancial Analyst10/31/2019Part-timeAhmed Aliaali@example.comreviewerv1{"location": {"address": "1234 West Street, Office 113, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
7Taro YamadaTaroYamadatyamada@example.comLegalContractsLawyer01/01/2020Full-timeMaria Gomezmgomez@example.comreviewerv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "IJKLMNOP"}
8Nadezhda IvanovaNadezhdaIvanovanivanova@example.comEngineeringHardwareMechanical Engineer03/15/2020ContractorAhmed Aliaali@example.comreviewerv1{"\location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
9Muhammad KhanMuhammadKhanmkhan@example.comCustomerSupportService06/30/2020Full-timeMaria Gomezmgomez@example.comreviewerv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}}
10Sanjay GuptaSanjayGuptasgupta@example.comResearchData ScienceResearch Analyst09/15/2020Full-timeAhmed Aliaali@example.comreviewerv1{"location": {"address": "1234 West Street, Office 111, Anytown, NY 12345"}, "role id": "ABCDEFGH"}
NOTE: Columns with * are required always.
Column Definitions#
Column NameColumn Description
User IDRequired - A unique identifier for the user. This is the internal balkan id of the user
Full NameOne 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 NameOne 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 NameOne 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 EmailRequired - The work email of the user. In the sample CSV, this is: aali@example.com, mgomez@example.com, etc.
DepartmentOptional - The user's department. In the sample CSV, this is: Sales, Marketing, etc.
TeamOptional - The user's team. In the sample CSV, this is: Enterprise, Brand, etc.
TitleOptional- The user's job title. In the sample CSV, this is: Sales Representative, Marketing Manager, etc.
Start DateRequired - The user's start date in MM/DD/YYYY format. In the sample CSV, this is: 01/21/2021, 07/13/2020, etc.
End DateOptional - 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 TypeOptional - The type of employment. In the sample CSV, this is: Full-time, Part-time, etc.
ManagerOptional - The full name of the user's manager. In the sample CSV, this is: Maria Gomez, Ahmed Ali, etc.
Manager Work EmailOptional - The work email of the user's manager. In the sample CSV, this is: mgomez@example.com, aali@example.com, etc.
Source User IDOptional - 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 RolesRequired - Roles of the User in the Balkan ID application. Can be - reviewer, riskmanager, admin
OrganizationOptional - The organization the user belongs to.
Metadata VersionOptional - 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), user (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 User integration (like Finch or Google) and then upload after edits to the User without losing relevant information about the original extraction from the integration - app (string), correlation id (string), tenant (string), timestamp (string).
MetadataOptional - Metadata that is to be added to the User. 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.

Request

Authorization
API Key
Add parameter in header
X-API-KEY-ID
Example:
X-API-KEY-ID: ********************
API Key
Add parameter in header
X-API-KEY-SECRET
Example:
X-API-KEY-SECRET: ********************
or
Header Params

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://balkanid.app/api/rest/v0/employees/download-url' \
--header 'X-Api-Key-ID;' \
--header 'X-Api-Key-Secret;' \
--header 'X-API-KEY-ID: <api-key>' \
--header 'X-API-KEY-SECRET: <api-key>' \
--header 'Content-Type: application/json'

Responses

🟢200OK
application/json
download url response
Bodyapplication/json

Example
{
    "url": "string",
    "pollingUrl": "string"
}
⚪defaultServer Error
Modified at 2026-11-06 13:38:07
Previous
Get Branding Information
Next
Bulk Employees Upload API
Built with