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 Upload API

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

BalkanID Employee Relations Upload CSV Format#

In this section, we will explain the BalkanID Employee Relations CSV format (employee to identity, credential or agent mappings). This endpoint replaces /relations/upload-url, which accepted the legacy relations.csv columns; the legacy column names are still accepted in uploads.
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

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 Employee Relations CSV format.

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/employee-relations/upload-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

🟢200
application/json
upload url response
Bodyapplication/json

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