Developer Hub
Request Demo
Request Demo
Support
  1. Reviews
  • 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)
      • Bulk Purposes Upload API (Early Access)
    • 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)
        POST
      • Bulk Reviews Upload API (Early Access)
        POST
    • 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. Reviews

Bulk Reviews Download API (Early Access)

POST
https://app.balkan.id/api/rest/v0/reviews/download-url
Reviews

BalkanID Access Reviews Download CSV Format#

In this section, we will explain the BalkanID Access Reviews CSV format.
Sample CSV
ID*Permission Name*Permission Value*ResourceResource TypeIdentity IDIdentity Type*Identity EmailIdentity UsernameIdentity NameEmployee IDEmployee EmailJob TitleDepartmentManagerEmployment TypeCampaign Name*Application Name*Application DescriptionConnectionConnection TypeReviewer*Reviewer ID*Access Review Creation Date*Access Review Completion DateReview Status*Activity LogReview TypeLabels ArrayRecommendationPurpose IDEmployee ID For Purpose
01H90W5FM2RY663D6AFNG9HEJ9ownerTRUEFrontend RepoRepository76yi-IQGt_K6apHfRslIOCs_bIn91x31Jaccv89pkc4employeejohn.doe@example.comjohn.doe@example.comJohn Doeemail/ujnknkjsndkjnkjbnarkjohn.doe@example.comEngineerEngineeringFull timeCampaign 1GithubGitHub is a code hosting platform for version control and collaborationreadrepository-roleJane Doejane.doe@example.com2023-08-29overdue[{"Actor ID":"john.doe@example.com","Actor Name":"John Doe","Activity Comment":","Previous Status":","Status":"created","Timestamp":"2023-08-29T14:46:36+00:00"},{"Actor ID":"jane.doe@example.com","Actor Name":"Jane Doe"Activity Comment":","Previous Status":"created","Status":"started","Timestamp":"2023-08-29T14:46:36+00:00"}]{"value": "approve", "explanation": "testing"}01H90W5FM2RY663D6AFNG9HEJ9email/ujnknkjsndkjnkjbnark
01H90W5FM2RY663D6AFP7DBEABownerTRUEBackend RepoRepository76yi-IQGt_K6apHfRslIOCs_bIn91x31Jaccv89pkc4employeejohn.doe@example.comjohn.doe@example.comJohn Doeemail/ujnknkjsndkjnkjbnarkjohn.doe@example.comEngineerEngineeringFull timeCampaign 1GithubGitHub is a code hosting platform for version control and collaborationwriterepository-roleJane Doejane.doe@example.com2023-08-29overdue[{"Actor ID":"john.doe@example.com","Actor Name":"John Doe","Activity Comment":","Previous Status":","Status":"created","Timestamp":"2023-08-29T14:46:36+00:00"},{"Actor ID":"jane.doe@example.com","Actor Name":"Jane Doe","Activity Comment":","Previous Status":"created","Status":"started","Timestamp":"2023-08-29T14:46:36+00:00"}]{"value": "deny", "explanation": "testing"}01H90W5FM2RY663D6AFNG9HEJ9email/ujnknkjsndkjnkjbnark
NOTE: Columns with * are required always.
Column Definitions#
Column NameColumn Description
IDRequired - This is a unique review ID for each entitlement generated by the BalkanID processing and serves as an identifier for each review as a part of a campaign.
Permission NameRequired - The name of action/permission/entitlement. These are typically actions that can be on a resource. In the sample CSV, these are “pull”, “push”, and “which are actions associated with a repository.
Permission ValueRequired - In many cases, these will be “true”. In some cases, it is useful to model an explicit deny by including entitlements where Privilege Value is “false”. In the sample CSV, we see both “true” and “false” privilege values.
ResourceOptional, Required if Resource Type is Present - The resource this entitlement references. In the sample CSV, the resource is the “ops” repository.
Resource TypeOptional, Required if Resource is Present - A useful resource type that groups resources in your application. This can be a Github repository/organization/application, AWS service, a Slack channel, etc. In the sample CSV, the resource type is “repository”.
ProjectOptional - The project to which the resource belongs, for which the access review needs to be done.
Identity IDUnique ID for each identity, generated by BalkanID.
Identity TypeRequired - The type of the identity. Can be any of employee, service account, or undefined.
Identity EmailOne of Email, User ID, or Username - The email associated with the identity to which this entitlement belongs to
Identity UsernameOne of Email, User ID, or Username - The username associated with the identity to which this entitlement belongs to
Identity NameOptional - The name of the identity to which this entitlement belongs to, if available. This can be the name of a person, a service account, or other names.
Employee IDUnique ID for the employee to which this entitlement belongs, generated by BalkanID.
Employee EmailOne of Email, User ID, or Username - The email associated with the employee to which this entitlement belongs
Job TitleThe job title of the identity, for which the access review needs to be done.
DepartmentThe department to which the identity belongs, for which the access review needs to be done.
ManagerThe name of the manager of the identity, for which the access review needs to be done.
Manager EmailThe email of the manager of the identity, for which the access review needs to be done.
Employment TypeEmployment type of the identity, such as Full-Time, Salaried, Contractor, Intern, etc.
Campaign NameRequired - Name of the Campaign to which the reviews belong to.
Campaign IDRequired - ID of the Campaign to which the reviews belong to.
Application Integration IDRequired - The unique ID of the application integration.
Application NameRequired - The name of the application for which the entitlements need to be reviewed.
Application DescriptionOptional - The description of the application for which the entitlements need to be reviewed.
ConnectionOptional, Required if Connection Type is Present - Connection describes how the identity (identified by the Username) gains the privilege (identified by Privilege Name and Privilege Value) to the resource (identified by Resource and Resource Type). In the sample CSV, the connection is the repository role granted to the identity: “read” and “admin”.
Connection TypeOptional, Required if Connection is Present - Connection Type describes the type of the Connection. Typical connection types are “role”, “policy”, “group”, but can include others depending on your application authorization structure. In the sample CSV, this is “repository-role”.
ReviewerRequired - The name of the identity to which this review is assigned. This can be the name of a person or other names.
Reviewer IDRequired - Email ID of the reviewer, the identity to which the review is assigned.
Created AtRequired - The date on which the access review was created in YYYY-MM-DD format.
Access Review Completion DateOptional, Required if access review is completed is Present - The date on which the access review was completed in YYYY-MM-DD format.
Review StatusRequired - This can be one of the following: created, started, stopped, approved, rejected, request_info, delegated
Activity LogOptional - List of actions performed on the entitlement.
Review TypeOptional - The type of the review.
Labels ArrayOptional - List of labels associated with the entitlement.
RecommendationOptional, Recommendation for the review. Format: {"value": One of {"approve", "deny" or "} , "explanation": "testing"}
Purpose IDOptional - The ID of the purpose associated with the purpose request.
Employee ID For PurposeOptional - The Unique ID of the employee, generated by BalkanID, associated with the purpose request.

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 Access Reviews 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

Header Params
X-Api-Key-ID
string 
optional
X-Api-Key-Secret
string 
optional
Content-Type
string 
optional
Default:
application/json
Body Params application/json
filter
object 
optional
Filter by a campaign or a request. Only one filter can be applied at a time.
campaign
object 
optional
Filter by a campaign. Only one campaign can be applied at a time.
created_at
string 
optional
Filter by the date and time the review was created. Supports filtering by greater than, less than, equal to, greater than or equal to, and less than or equal to. Use the prefixes gt:, lt:, eq:, gte:, or lte: before the datetime to filter accordingly. Additionally, logical operators && (AND), || (OR), and ! (NOT) can be used for complex filtering. For example, !gt:2024-06-13T23:59:59&&lte:2024-06-16 to filter for reviews not created after June 13, 2024, 11:59:59 PM and on or before June 16, 2024. The datetime can be in the format YYYY-MM-DDTHH:MM:SS or just the date in YYYY/MM/DD or YYYY-MM-DD format. Time is optional.
request
object 
optional
Filter by a request. Only one request can be applied at a time.
updated_at
string 
optional
Filter by the date and time the review was last updated. Supports filtering by greater than, less than, equal to, greater than or equal to, and less than or equal to. Use the prefixes gt:, lt:, eq:, gte:, or lte: before the datetime to filter accordingly. Additionally, logical operators && (AND), || (OR), and ! (NOT) can be used for complex filtering. For example, !gt:2024-06-13T23:59:59&&lte:2024-06-16 to filter for reviews not updated after June 13, 2024, 11:59:59 PM and on or before June 16, 2024. The datetime can be in the format YYYY-MM-DDTHH:MM:SS or just the date in YYYY/MM/DD or YYYY-MM-DD format Time is optional.
includeActivityLog
boolean 
required
Include the activity log for each review.
Example
{
    "filter": {
        "campaign": {
            "id": "string",
            "source": "string",
            "sourceID": "string"
        },
        "created_at": "string",
        "request": {
            "id": "string",
            "source": "string",
            "sourceID": "string"
        },
        "updated_at": "string"
    },
    "includeActivityLog": true
}

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/reviews/download-url' \
--header 'X-Api-Key-ID;' \
--header 'X-Api-Key-Secret;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "filter": {
        "campaign": {
            "id": "string",
            "source": "string",
            "sourceID": "string"
        },
        "created_at": "string",
        "request": {
            "id": "string",
            "source": "string",
            "sourceID": "string"
        },
        "updated_at": "string"
    },
    "includeActivityLog": true
}'

Responses

🟢200OK
application/json
download url response
Body
Download URL endpoint response
pollingUrl
string 
required
The value is the polling URL which you will use to poll to find if the data is ready for download.
url
string 
required
The value is the download URL from which you will download your CSV file.
Example
{
    "pollingUrl": "string",
    "url": "string"
}
🔴500Server Error
Modified at 2025-04-10 03:44:22
Previous
Bulk Requests Upload API (Early Access)
Next
Bulk Reviews Upload API (Early Access)
Built with