Batches

Overview

The Batches endpoints provide access to pre-generated bulk data files for your organization. Batch files contain large datasets in a compressed JSON Lines format, suitable for offline processing and full-data synchronization.

A batch refers to a file that can be downloaded from the API. These files are provided in the brotli-format, which when unpackaged contains a JSON-file with the information for one company per row in the file.

While requesting items using our endpoints are limited, the batches allows for delivery of larger sets of data, where creation is scheduled to occur during off-hours. Currently, a large volume is defined as exceeding 100,000 units.

Using batches we create full packages of entire countries on a regular basis, either baselifts and/or incremental delta-files for updates.

We offer batches representing the data from the endpoints companies and relations.

A batch job is the only way to access sets exceeding 100.000 companies. Contact our support team at [email protected] to see which batches are available or to get help setting up your own tailored batch.

Batch files are available for 60 days from creation. After that, they are removed from the list.

Batch files are scoped to your client organization — you can only list and download files assigned to your account.

Authentication

All requests require authentication. Include your access token in the Authorization header:

Authorization: Bearer <access-token>

If authentication fails, the endpoint returns HTTP 401 Unauthorized.

List Batch Files

Endpoint: GET /v2/batches/batch-files

Request

No request body or query parameters are required.

Example request:

GET /v2/batches/batch-files
Authorization: Bearer <access-token>

Success Response (HTTP 200)

Returns a GetBatchListResponse JSON body.

Example response:

{
  "Batches": [
    {
      "BatchFileId": 42,
      "FileName": "companies_se_2026_05.br",
      "Description": "A JSON Lines file compressed using Brotli.",
      "CreatedAt": "2026-05-15T08:00:00Z",
      "FileSizeGB": 1.25
    },
    {
      "BatchFileId": 43,
      "FileName": "relations_no_2026_05.br",
      "Description": "A JSON Lines file compressed using Brotli.",
      "CreatedAt": "2026-05-20T08:00:00Z",
      "FileSizeGB": 0.85
    }
  ]
}

Returns an empty Batches array when no batch files are available for your account.

Unauthorized Response (HTTP 401)

Returned with an empty body when authentication fails.

Download Batch File

Endpoint: GET /v2/batches/batch-file/{batchFileId}

Request

Example request:

GET /v2/batches/batch-file/42
Authorization: Bearer <access-token>

Success Response (HTTP 200)

Returns the file as a binary download:

The response body is the raw file bytes. No JSON wrapper is returned.

Unauthorized Response (HTTP 401)

Returned when:

• Authentication fails, or
• The batch file ID exists but is not authorized for your client organization.

Not Found Response (HTTP 404)

Returned when the batch file ID is authorized for your account but the file content cannot be retrieved from storage.

Batch Object

Each item in the Batches array from the list endpoint.

File Format

Batch files are JSON Lines (one JSON object per line) compressed with Brotli compression (.br extension).

Typical workflow:

1. Call GET /v2/batches/batch-files to discover available files.
2. Download the desired file via GET /v2/batches/batch-file/{batchFileId}.
3. Decompress the file using Brotli.
4. Process each line as an independent JSON object.

Note: The exact schema of each JSON line depends on the batch file type (companies, relations, etc.). Contact Valu8 support for schema documentation specific to your batch files.

JSON Serialization Behavior

The list endpoint returns JSON.

The download endpoint returns binary content, not JSON.