Developer Hub
Request Demo
Request Demo
Support
  1. Relations
  • 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
      • Bulk Employees Upload API
    • 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. Relations

Bulk Employee Relations Download API

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

BalkanID Employee Relations Download CSV Format#

In this section, we will explain the BalkanID Employee Relations CSV format.
The file contains the existing employee mappings of either identities, credentials or agents, never more than one in one file. Pass targetType in the optional JSON request body to choose: identity (default), credential or agent. A file of one target type has that value in every Target Type column; to export several target types, request the download once per target type. The request body is optional, an empty request exports all identities, mapped and unmapped.
Request options (all optional)
PropertyDescription
targetTypeidentity (default), credential or agent.
withMappedDefault true. Include targets mapped to an employee (owner and accessible_by rows).
withUnmappedDefault true. Include targets without an owner, one row per target with no employee. If both withMapped and withUnmapped are false the file has no rows.
Sample CSV
AppIntegration IDEmployee IDEmployee EmailTarget IDTarget Source IDTarget UsernameTarget EmailTarget TypeRelation TypeSource SystemMetadata VersionMetadataTimestamp
awsaws/01FX103897S15JVJAR17GS3SQTsam@example.comid/U-ysy2l6niyJmThu_Z-9urozE8tQBAEmJhjZ4nVxphgidentityowneremployee_relations_csv
oktaokta/01H965ZRNQHAS2B8GKJA85X75Cemail/CUp7jz61_N5K2qctJNyKsSFy1pZSpDneEStYN89dImwjames@example.comidentityaccessible_byemployee_relations_csv
azuresam@example.com6f1c0f0e-sample-source-idcredentialowneremployee_relations_csv
awsaws/01FX103897S15JVJAR17GS3SQCid/xjyKMctjdu6l3iaJwo6OkvJ8BMtvFrmWEz4yIK5xrksidentityunmappedemployee_relations_csv
NOTE: At least one of App or Integration ID is required (agents may have no integration, so they are exempt and are located by Target ID or Target Source ID alone), at least one of Employee ID or Employee Email is required for owner, accessible_by and remove_accessible_by rows, and at least one target locator (Target ID, Target Source ID, Target Username, Target Email) is required.
Column Definitions#
Column NameColumn Description
AppOptional if Integration ID is set, the app slug of the target's integration (for example okta). An app alone resolves to its single active integration; if the app has none or more than one active integration the row is rejected and you must give the Integration ID.
Integration IDOptional if App is set, the integration id of the target (for example okta/01H965ZRNQHAS2B8GKJA85X75C). When both are given they must agree. The target is looked up inside this integration.
Employee IDOptional if Employee Email is set, the BalkanID employee id
Employee EmailOptional if Employee ID is set, the work email of the employee in the BalkanID tenant
Target IDOptional, the BalkanID id of the identity, credential or agent
Target Source IDOptional, the id of the identity, credential or agent in its application
Target UsernameOptional, identities only, the username of the identity
Target EmailOptional, identities only, the email of the identity
Target TypeOptional, identity (default), credential or agent. A credential or agent row must not set Target Username or Target Email.
Relation TypeOptional, owner (default), accessible_by, remove_owner, remove_accessible_by, or unmapped (identities only). Use unmapped to explicitly remove an existing mapping and prevent integration syncs from re-establishing it automatically. Removals only remove mappings that were made manually, never mappings set by an integration.
Source SystemOptional, employee_relations_csv (default) for uploads. integrations is reserved for integration extractors: rows with this Source System are skipped in a manual upload (reported as one aggregated warning) and do not fail the upload.
Metadata VersionOptional, must be given together with Metadata
MetadataOptional, JSON, must be given together with Metadata Version
TimestampOptional, unix timestamp in seconds

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 Employee Relations 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

Body Params application/json

Example
{
    "targetType": "identity",
    "withMapped": true,
    "withUnmapped": true
}

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 'https://balkanid.app/api/rest/v0/employee-relations/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' \
--data '{
    "targetType": "identity",
    "withMapped": true,
    "withUnmapped": true
}'

Responses

🟢200
application/json
download url response
Bodyapplication/json

Example
{
    "url": "string",
    "pollingUrl": "string"
}
⚪default
Modified at 2026-11-06 14:33:25
Previous
Bulk Employee Relations Upload API
Next
AdminsDownloadURLRequest
Built with