# CompanyBook.BG

> 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. The public website supports regular search for companies and people. Customer API access requires an API key.

## API Documentation

- [Full API Documentation](https://companybook.bg/api-docs): Complete reference for endpoints, parameters, access tiers, and response formats
- [Full LLMs File](https://companybook.bg/llms-full.txt): Expanded reference with examples and request/response bodies

## Access Tiers

### No registration
- 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
- Customer API key from the account page
- 100 API requests per day
- Regular API search: company search by UIC/name/district/legal form/status/VAT/NKID/contact presence, people search, and unified search
- Financial data API for older fiscal years, limited to 30 distinct company-and-year combinations per day

### Pro subscription / paid API key
- Two plans with the same features and different daily limits:
  - Pro (annual), €249.99/year + VAT: 3,000 API requests per day, 300 distinct company-and-year combinations of financial data per day, Excel exports of up to 2,000 companies per day
  - Pro Lite (monthly), €29.99/month + VAT: 1,000 API requests per day, 100 distinct company-and-year combinations of financial data per day, 30 Excel exports per month (up to 1,000 companies per day)
- Pro company search controls: financial-data availability, revenue buckets, registration year/date filters, and financial sorting
- Financial data for every available fiscal year, including the most recent paid years, within the plan's daily company-and-year allowance
- Website features such as larger exports, company lists, higher tracking limits, and Pro bankruptcy data

## Authentication

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

1. Register for free at [companybook.bg/sign-up](https://companybook.bg/sign-up)
2. Get your API key from your account page

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

## Main API Endpoints

### Companies
- GET /api/companies/:uic - Get company by UIC. Requires any valid API key.
- GET /api/v2/companies/search - Search companies. Regular parameters work with any valid API key; Pro filters and sorting require a paid API key.
- GET /api/companies/:uic/financial?year=YYYY - Get company financial data for one fiscal year. The `year` query parameter is required and the response contains only that year. Free keys receive older-year access; paid keys receive access to every available year. Metered as distinct company-and-year combinations per day; repeats of the same company-and-year on the same day are free.
- GET /api/companies/:uic/download - Download specific company documents. Requires website session authentication, not an API key.

### People
- GET /api/people/:indent - Get person by identifier. Requires any valid API key.
- GET /api/v2/people/search - Search people by name. Requires any valid API key.

### Unified Search
- GET /api/v2/shared/search - Search companies and people simultaneously. Requires any valid API key.

## Company Search Parameters

Regular parameters available to any valid API key:
- `uic`, `name`, `district`, `status`, `legal_form`, `vat`, `has_contact_data`, `limit`, `offset`

Pro parameters requiring a paid API key:
- `has_active_financial_data`, `revenue_range`, `registration_year_from`, `registration_year_to`, `registration_date_from`, `registration_date_to`, `sort_by`, `sort_dir`

Search results expose contact presence booleans for email/phone/website availability. They do not expose raw contact values in public search results.

## General Information

- Base API URL: https://api.companybook.bg
- Response format: JSON
- Search pagination uses `limit` and `offset`
- Public search is bounded to the backend-supported result window
- `with_data=true` search hydration is restricted and is not available to normal customer API keys