Bulk Entities + Entity-Relations Zip Upload API

POST

https://app.balkan.id/api/rest/v0/entities-bulk/upload-url

Returns a pre-signed S3 URL for uploading a single zip containing both
entities.csv and entity_relations.csv for an integration. Both files
are processed under one correlation ID and trigger a single after-sync,
avoiding the race introduced by the legacy /entities/upload-url and
/entity-relations/upload-url flows.

Zip layout

The zip MUST contain at the root:

entities.csv — see /entities/upload-url for the column schema

entity_relations.csv — see /entity-relations/upload-url for the column schema

Other files inside the zip are ignored.

Upload via the pre-signed URL

Request

Authorization

API Key

Add parameter in header

X-API-KEY-ID

Example:

X-API-KEY-ID: ********************

Header Params

Body Params application/jsonRequired

Example

{
    "integrationID": "string"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://app.balkan.id/api/rest/v0/entities-bulk/upload-url' \
--header 'X-Api-Key-ID;' \
--header 'X-Api-Key-Secret;' \
--header 'X-API-KEY-ID: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "integrationID": "string"
}'

Responses

🟢200

application/json

upload url response

Bodyapplication/json

Example

{
    "url": "string"
}

⚪default

Modified at 2026-08-21 00:28:00

Bulk Entities Upload API (Early Access)

Bulk Entity Insights Download API (Early Access)