Developer Hub
Request Demo
Request Demo
Support
  1. Purposes
  • Getting Started
    • Introduction
  • API Reference
    • Admins
      • Bulk Admins Download API (Early Access)
    • Apps
      • Bulk Apps Download API (Early Access)
    • Business Owners
      • Bulk Business Owners Download API (Early Access)
      • Bulk Business Owners Upload API (Early Access)
    • Campaigns
      • Bulk Campaigns Download API (Early Access)
      • Bulk Campaigns Upload API (Early Access)
    • Configuration
      • Bulk Applied Labels Upload API (Early Access)
      • Bulk Entity Finding Rules Download API (Early Access)
      • Bulk Custom Insights (Entity Rules) Download API (Early Access)
      • Bulk Filters Download API (Early Access)
      • Bulk Filters Upload API (Early Access)
      • Bulk Findings Download API (Early Access)
      • Bulk Findings Upload API (Early Access)
      • Bulk Labels Download API (Early Access)
      • Bulk Labels Upload API (Early Access)
      • Bulk Privileged Download API (Early Access)
      • Bulk Privileged Upload API (Early Access)
      • Bulk RBAC Download API (Early Access)
      • Bulk RBAC Upload API (Early Access)
      • Bulk RBAC2 Download API (Early Access)
      • Bulk RBAC2 Upload API (Early Access)
      • Bulk Rules Download API (Early Access)
      • Bulk Rules Upload API (Early Access)
    • Employees
      • Bulk Employees Download API (Early Access)
      • Bulk Employees Upload API (Early Access)
    • Entitlements
      • Bulk Entitlements Download API (Early Access)
      • Bulk Entitlements Upload API (Early Access)
    • Entities
      • Bulk Entities Download API (Early Access)
      • Bulk Entities Upload API (Early Access)
    • EntityInsights
      • Bulk Entity Insights Download API (Early Access)
      • Bulk Entity Insights Upload API (Early Access)
    • EntityRelations
      • Bulk Entity Relations Download API (Early Access)
      • Bulk Entity Relations Upload API (Early Access)
    • EntityRBAC
      • Bulk Entity RBAC Download API
      • Bulk Entity RBAC Upload API
    • Integrations
      • Bulk Integrations Download API (Early Access)
      • Bulk Integrations Upload API (Early Access)
    • Purposes
      • Bulk Purposes Download API (Early Access)
        POST
      • Bulk Purposes Upload API (Early Access)
        POST
    • Relations
      • Bulk Relations Download API (Early Access)
      • Bulk Relations Upload API (Early Access)
    • Requests
      • Bulk Requests Download API (Early Access)
      • Bulk Requests Upload API (Early Access)
    • Reviews
      • Bulk Reviews Download API (Early Access)
      • Bulk Reviews Upload API (Early Access)
    • Playbooks
      • Bulk Playbook Templates Download API (Early Access)
      • Bulk Playbook Templates API (Early Access)
    • Webhooks
      • Bulk Webhook Templates Download API (Early Access)
      • Bulk Webhook Templates API (Early Access)
  • Playbooks
    • Overview
  1. Purposes

Bulk Purposes Upload API (Early Access)

POST
https://app.balkan.id/api/rest/v0/purposes/upload-url
Purposes

BalkanID Purposes Upload CSV Format#

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

Sample CSV#

BRNPurpose Name*Description*Pre-Expiry NotificationDepartmentJob TitleTeamOwnerBirthrightStatusEntity BRNs*
Kubernetes DevelopmentPurpose which is meant for Kubernetes Development168hSoftware DevelopmentSoftware Development EngineerSoftwareaali@example.comDepartment Birthrightbrn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q0, brn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q1
Infrastructure DevOpsPurpose which is meant for Infrastucture DevOps168hDevOpsDevOps EngineerDevOpsmgomez@example.comDepartment Birthrightbrn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q2, brn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q3
brn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:purpose:01JH1JR91K9N91Z04PHK2201WQProduction OncallPurpose which is meant for Production Oncall2hCustomer SupportCustomer SupportCustomer Supportxliu@example.comTeam Birthrightbrn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q4
brn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:purpose:01JH1JR91K9N91Z04PHK2201WSLocal Stack DevelopmentPurpose which is meant for Local Stack Development48hSoftware DevelopmentSoftware Development EngineerSoftwarefasaud@example.comOrganization Birthrightdeletedbrn:bid:balkanid:::01HWBCYJA11R3AA48K5V0DVM00:identity:04giq7jlHzhHyZ-cOvAn4Fn2dNc3bjqZrK4ufzx19Q0
Columns with * are required always.
Column Definitions#
Column NameColumn Description
BRNBalkan Resource Name
Purpose NameRequired - Name of the purpose
DescriptionRequired - Description of the purpose
Pre-Expiry NotificationTime duration before expiry of purpose request at which a notification is sent out
DepartmentDepartment associated to the purpose
Job TitleJob Title associated to the purpose
TeamTeam associated to the purpose
OwnerOwner of the entity
BirthrightBirthright that the purpose represents
StatusUsed for deleting an existing Purpose ("deleted" or empty)
Entity BRNsRequired - Comma separated list of Entity BRNs that are granted access to when starting a purpose
"Purpose Name" and "Description" are required columns.
If a BRN is not provided, a new Purpose will be created. If a BRN is provided, an existing Purpose with the BRN will be updated and if an existing Purpose does not exist, a new Purpose will be created with the input BRN.
The only valid values for "Pre-Expiry Notification" are '', '2h', '4h', '24h', '48h', '168h'.
BRNs for the "Entity BRNs" column can be obtained by downloading the Entities using the Bulk Entities Download API.

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 Purposes CSV format.

Request

Header Params
X-Api-Key-ID
string 
optional
X-Api-Key-Secret
string 
optional
Content-Type
string 
optional
Default:
application/json

Request 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://app.balkan.id/api/rest/v0/purposes/upload-url' \
--header 'X-Api-Key-ID;' \
--header 'X-Api-Key-Secret;' \
--header 'Content-Type: application/json'

Responses

🟢200OK
application/json
upload url response
Body
Upload URL endpoint response
url
string 
required
The value is the pre-signed URL to which to upload your CSV file.
Example
{
    "url": "string"
}
🔴500Server Error
Modified at 2025-04-10 03:44:22
Previous
Bulk Purposes Download API (Early Access)
Next
Bulk Relations Download API (Early Access)
Built with