# CompanyBook.BG - Full API Reference

> Bulgarian company registry with company, person, financial, contact-presence, and relationship data through the website and REST API

CompanyBook.BG is a searchable database of Bulgarian companies and people, sourced from the official Bulgarian Trade Register.

## API Documentation

- [Full API Documentation](https://companybook.bg/api-docs): Interactive reference with code examples
- Base API URL: https://api.companybook.bg
- Response format: JSON

## Access Tiers

### No registration

No-registration access is for the public website, not direct customer API calls.

- Public website regular company and people search
- Company and person detail pages
- Free tools such as VIES checks and calculators

### Free account / free API key

Create a free account to get a customer API key from the account page.

- 100 API requests per day
- Company lookups by UIC
- Person lookups by identifier
- Regular company search by UIC, name, district, legal form, status, VAT, NKID, and contact presence
- People search
- Unified company/person search
- Financial data API for older years, limited to 30 unique UICs per day

### Paid subscription / paid API key

A paid subscription upgrades the user's API key and website session.

- 3,000 API requests per day
- Premium company search controls:
  - Financial-data availability filters
  - Revenue bucket filters
  - Registration year/date filters
  - Financial sorting by revenue, profit, assets, equity, and EBITDA
- Full financial data including the latest paid financial year, limited to 300 unique UICs per day
- Website features such as larger exports, company lists, higher tracking limits, and premium bankruptcy data

## Authentication

Customer API requests require a valid API key passed via the `X-API-Key` HTTP header:

```http
X-API-Key: your_api_key_here
```

How to get an API key:

1. Register for free at [companybook.bg/sign-up](https://companybook.bg/sign-up)
2. Open your account page
3. Copy the API key from the security/API key section

Daily request limits:

- Free account API keys: 100 requests per day
- Paid API keys: 3,000 requests per day
- Limits reset daily at midnight (EET/EEST)

## Companies API

### GET /api/companies/:uic

Get company information by UIC.

Authentication: any valid API key

Parameters:

- `uic` (required): Company UIC, accepts with or without `BG` prefix
- `with_data` (optional): Boolean. `false` returns basic data; `true` returns expanded company data when available for the key/session.

Basic response:

```json
{
  "uic": "123456789",
  "name": "Example Ltd",
  "legalForm": "OOD",
  "status": "N",
  "transliteration": "Example OOD"
}
```

Expanded response shape:

```json
{
  "company": {
    "uic": "123456789",
    "companyName": { "name": "Example Ltd" },
    "legalForm": "OOD",
    "status": "N",
    "seat": { "country": "Bulgaria", "address": "..." },
    "contacts": { "email": "...", "phone": "...", "website": "..." },
    "managers": [],
    "partners": [],
    "nkids": [],
    "lastUpdated": "..."
  },
  "history": [],
  "daughters": []
}
```

### GET /api/v2/companies/search

Search companies with regular or premium filters.

Authentication: any valid API key for regular search; paid API key for premium search controls

Regular parameters available to any valid API key:

- `uic` (string): Exact UIC
- `name` (string): Company name
- `district` (string): District ID
- `status` (boolean): Active/inactive
- `legal_form` (string): Legal form
- `vat` (boolean): VAT registration status
- `has_contact_data` (boolean): Companies with at least one public contact-presence signal
- `limit` (integer): Results per page
- `offset` (integer): Pagination offset within the supported result window

Premium parameters requiring a paid API key:

- `has_active_financial_data` (boolean): Companies with active-year financial data
- `revenue_range` (string): One of `0`, `0_100k`, `100k_1m`, `1m_5m`, `5m_15m`, `15m_40m`, `40m_100m`, `100m_plus`
- `registration_year_from` (integer): Registration year lower bound
- `registration_year_to` (integer): Registration year upper bound
- `registration_date_from` (string): Registration date lower bound, `YYYY-MM-DD`
- `registration_date_to` (string): Registration date upper bound, `YYYY-MM-DD`
- `sort_by` (string): `revenue`, `net_profit`, `accounting_profit`, `assets`, `equity`, or `ebitda`
- `sort_dir` (string): `asc` or `desc`

Notes:

- Search results expose Contact Presence for email/phone/website availability.
- Search results do not expose raw contact values.
- Search returns at most the first 1000 ranked matches. Counts above that are shown as `1000+`.
- Search uses `limit` and `offset` pagination.
- `with_data=true` search hydration is restricted and is not available to normal customer API keys.

Response:

```json
{
  "results": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "OOD",
      "status": "N",
      "district": "Sofia",
      "transliteration": "Example Ltd",
      "vatRegistered": true,
      "contactPresence": {
        "email": true,
        "phone": false,
        "website": true
      },
      "activeFinancialYear": 2024,
      "latestRevenue": "1M - 5M"
    }
  ],
  "total": "1000+",
  "totalCount": 1000,
  "hasMoreTotal": true,
  "limit": 20,
  "offset": 0
}
```

### GET /api/companies/:uic/financial

Get company financial data by year.

Authentication: API key or website session cookie

Access control:

- Free account/API key: older-year financial data; latest paid financial year is withheld
- Paid subscription/API key: full financial data for all available years

Financial data limits:

- Free account/API key: 30 unique UICs per day
- Paid subscription/API key: 300 unique UICs per day

Parameters:

- `uic` (required): Company UIC, accepts with or without `BG` prefix

Response:

```json
{
  "uic": "123456789",
  "last_updated": "2024-01-15",
  "financial_data": {
    "2023": {
      "income_statement": {
        "revenue": { "total": 1500000, "net_total": 1450000 },
        "expenses": { "total": 1200000, "profit": 270000 }
      },
      "balance_sheet": {
        "assets": { "total": 1650000 },
        "liabilities": { "equity": 800000, "total_liabilities": 850000 }
      },
      "general_info": {
        "revenue": 1500000,
        "profit": 270000,
        "roa": 16.36,
        "profit_margin": 18.0,
        "roe": 33.75
      }
    }
  },
  "has_2024_data": true
}
```

### GET /api/companies/:uic/download

Download a specific company document.

Authentication: website session cookie required, not API key

Rate limit: 20 downloads per minute per user

Parameters:

- `uic` (required): Company UIC
- `id` (required): Document ID from the company page
- `type` (required): `financial`, `statements_aj`, or `statements_bh`
- `year` (optional): Document year, required for some document types

## People API

### GET /api/people/:indent

Get person information by identifier.

Authentication: any valid API key

Parameters:

- `indent` (required): Person identifier
- `with_data` (optional): Boolean. Returns full company list when `true`.

### GET /api/v2/people/search

Search people by name.

Authentication: any valid free or paid API key

Parameters:

- `name` (required): Person name, minimum 3 characters
- `with_data` (optional): Boolean
- `limit` (integer): Results per page
- `offset` (integer): Pagination offset within the supported result window

Response:

```json
{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Ivan Petrov",
      "indent": "1234567890",
      "companies": 3
    }
  ],
  "total": "42",
  "totalCount": 42,
  "hasMoreTotal": false,
  "limit": 20,
  "offset": 0
}
```

## Unified Search API

### GET /api/v2/shared/search

Search companies and people simultaneously.

Authentication: any valid free or paid API key

Parameters:

- `name` (required): Search query, minimum 3 characters
- `limit` (integer): Results per type, default 3, max 500

Response:

```json
{
  "companies": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "OOD",
      "status": "N"
    }
  ],
  "people": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Ivan Petrov",
      "indent": "1234567890",
      "companies": 3
    }
  ]
}
```

## Code Examples

### JavaScript / TypeScript

```javascript
const API_KEY = "your_api_key_here";
const headers = { "X-API-Key": API_KEY };

// Any valid API key: regular company search
const regularSearchResponse = await fetch(
  "https://api.companybook.bg/api/v2/companies/search?name=Example&district=1&status=true",
  { headers }
);
const regularSearch = await regularSearchResponse.json();

// Paid API key: premium company search controls
const premiumSearchResponse = await fetch(
  "https://api.companybook.bg/api/v2/companies/search?revenue_range=1m_5m&sort_by=revenue&sort_dir=desc",
  { headers }
);
const premiumSearch = await premiumSearchResponse.json();

// Any valid API key: people search
const peopleResponse = await fetch(
  "https://api.companybook.bg/api/v2/people/search?name=Ivan&limit=20",
  { headers }
);
const people = await peopleResponse.json();

// Any valid API key: unified search
const unifiedResponse = await fetch(
  "https://api.companybook.bg/api/v2/shared/search?name=Example&limit=5",
  { headers }
);
const unified = await unifiedResponse.json();

// Financial data: older years for free keys, full available years for paid keys
const financialResponse = await fetch(
  "https://api.companybook.bg/api/companies/123456789/financial",
  { headers }
);
const financial = await financialResponse.json();
```

### Python

```python
import requests

API_KEY = "your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}

# Any valid API key: regular company search
regular_search = requests.get(
    "https://api.companybook.bg/api/v2/companies/search",
    params={"name": "Example", "district": 1, "status": True},
    headers=HEADERS,
).json()

# Paid API key: premium company search controls
premium_search = requests.get(
    "https://api.companybook.bg/api/v2/companies/search",
    params={"revenue_range": "1m_5m", "sort_by": "revenue", "sort_dir": "desc"},
    headers=HEADERS,
).json()

# Any valid API key: people search
people = requests.get(
    "https://api.companybook.bg/api/v2/people/search",
    params={"name": "Ivan", "limit": 20},
    headers=HEADERS,
).json()

# Financial data: older years for free keys, full available years for paid keys
financial = requests.get(
    "https://api.companybook.bg/api/companies/123456789/financial",
    headers=HEADERS,
).json()
```

### cURL

```bash
# Any valid API key: regular company search
curl "https://api.companybook.bg/api/v2/companies/search?name=Example&district=1&status=true" \
  -H "X-API-Key: your_api_key_here"

# Paid API key: premium company search controls
curl "https://api.companybook.bg/api/v2/companies/search?revenue_range=1m_5m&sort_by=revenue&sort_dir=desc" \
  -H "X-API-Key: your_api_key_here"

# Any valid API key: people search
curl "https://api.companybook.bg/api/v2/people/search?name=Ivan&limit=20" \
  -H "X-API-Key: your_api_key_here"

# Any valid API key: unified search
curl "https://api.companybook.bg/api/v2/shared/search?name=Example&limit=5" \
  -H "X-API-Key: your_api_key_here"

# Financial data: older years for free keys, full available years for paid keys
curl "https://api.companybook.bg/api/companies/123456789/financial" \
  -H "X-API-Key: your_api_key_here"
```

## Error Codes

- 200 - Success
- 400 - Bad Request: invalid or missing parameters
- 401 - Unauthorized: missing or invalid API key/session
- 403 - Forbidden: the API key or session does not have access, commonly when a free key uses paid-only search controls
- 404 - Not Found
- 429 - Too Many Requests: rate limit exceeded
- 500 - Internal Server Error

## Website Routes

- `/`: Homepage with public search
- `/search`: Search interface
- `/search/companies`: Company search
- `/search/people`: People search
- `/companies/:uic`: Company detail pages
- `/people/:indent`: Person detail pages
- `/api-docs`: API documentation
- `/subscribe`: Plan comparison and paid subscription